servicenow-nodejs

Happy MCP サーバー

ServiceNow® プラットフォーム向け Model Context Protocol サーバー

メタデータ駆動型の MCP サーバーです。160 以上のテーブルに対応する 480 以上のツールを自動生成し、複数インスタンスのサポート、自然言語検索、ローカルでのスクリプト開発を提供します。

ウェブサイト | GitHub | npm | ツール | コントリビューション | サポート

---

servicenow-mcp-server から移行する場合 npm パッケージ名は happy-platform-mcp に、Docker イメージ名は nczitzer/happy-platform-mcp に変更されました。以前の名前は非推奨ですが、当面は引き続き使用できます。依存関係を更新してください。

# npm
npm uninstall servicenow-mcp-server && npm install happy-platform-mcp

# Docker
docker pull nczitzer/happy-platform-mcp:latest

サポート

このプロジェクトが役立つと感じた場合は、開発への支援をご検討ください。ご支援は Happy Technologies LLC に役立てられます。

• GitHub Sponsors
• Buy Me a Coffee

機能

• 複数インスタンスのサポート — リクエストごとのルーティングにより、複数の ServiceNow® インスタンスに同時接続できます
• OAuth 2.0 と Basic Auth — インスタンスごとのクライアントクレデンシャル、リソースオーナーパスワードクレデンシャル、および PKCE を使用したユーザーごとの認可コードに対応します
• インテリジェントなスキーマ検出 — 実行時にテーブル構造とリレーションシップを自動検出します
• 160 以上のテーブル — ITSM、CMDB、サービスカタログ、プラットフォーム開発、Flow Designer を含む完全なカバレッジ
• 55 個の MCP ツール — あらゆるテーブルで動作する汎用 CRUD 操作に加え、便利な専用ツールを提供します
• バッチ操作 — 43 件以上の並列操作で正常に動作することを確認済みです
• ローカルでのスクリプト開発 — Git とのスクリプト同期、継続的な開発のためのウォッチモード
• 自然言語検索 — エンコードされたクエリの代わりに、平易な英語で検索できます
• MCP リソース — すばやい参照やドキュメント確認に使える、読み取り専用のリソース URI を 8 個提供します
• バックグラウンドスクリプト実行 — sys_trigger によるサーバーサイドスクリプトの自動実行
• サービスカタログの AI 送信 — サービスカタログのフォームをプログラムから閲覧、確認、送信できます
• ServiceNow ドキュメント検索 — GitHub を利用した任意のドキュメント取得と、公式 ServiceNowDocs の Markdown を対象としたローカル SQLite FTS 検索

クイックスタート

前提条件

• Node.js 20+
• REST API アクセスが可能な 1 つ以上の ServiceNow® インスタンス
• 各インスタンスの有効な認証情報

npm からインストール

npx happy-platform-mcp

または、グローバルにインストールします。

npm install -g happy-platform-mcp

ソースからインストール

git clone https://github.com/Happy-Technologies-LLC/happy-platform-mcp.git
cd happy-platform-mcp
npm install
# Source checkout: use node src/cli.js <command>, or npm link first.
node src/cli.js instance list

stdio サーバーを起動する

グローバルインストール後、引数なしで happy-platform-mcp を実行すると、 stdio MCP サーバーが起動します。

npm install -g happy-platform-mcp
SERVICENOW_INSTANCE=dev happy-platform-mcp

MCP ホストでは、グローバルコマンドを使用できます。

{
  "mcpServers": {
    "happy-mcp-server": {
      "command": "happy-platform-mcp",
      "env": { "SERVICENOW_INSTANCE": "dev" }
    }
  }
}

または、command: "npx" と args: ["-y", "happy-platform-mcp"] を指定して npx を使用します。 ソースをチェックアウトした場合は、node src/stdio-server.js を使用します。ソースから実行する CLI コマンドには、 node src/cli.js instance ... を使用します。

インスタンスの設定

推奨：ローカル CLI でメタデータを登録する

CLI は、起動したプロセスの環境を引き継ぎます。CLI は .env を自動的に読み込みません。.env の読み込みが適用されるのは、サーバー／stdio プロセスのみです。CLI を使用する場合は、シェルで HAPPY_CONFIG_PATH をエクスポートします（または、ホストが CLI を起動するときの MCP ホスト環境に設定します）。すべての OS で実際のデフォルトレジストリパスは <homedir>/.config/happy-platform-mcp/instances.json であり、その OS のネイティブなパス区切り文字が使用されます。

認証情報はローカルでプロンプト表示され、マスクされた状態でオペレーティングシステムのキーチェーンに保存されます。CLI が新規に書き込むバージョン 1 のレジストリには、インスタンスのメタデータと正規の credentialRef 値のみが含まれ、平文の認証情報は含まれません。レガシー形式の平文レジストリファイルは、読み取り専用の互換性入力として扱われます。また、単一の SERVICENOW_* 環境変数によるフォールバックは、後方互換性のためにのみ維持されています。

happy-platform-mcp instance add
happy-platform-mcp instance list
happy-platform-mcp instance test dev
happy-platform-mcp instance update dev
happy-platform-mcp instance remove dev
happy-platform-mcp instance migrate

instance add は、選択した認証モードで必要な認証情報を一度プロンプト表示し、メタデータを登録する前に保存します。instance credential set は、既存の認証情報のローテーション、またはメタデータのみの MCP 登録を完了する場合にのみ使用します。instance update はメタデータのみを変更します。認証方式を変更するには、instance remove の後に instance add を実行する必要があります。シークレットのプロンプト入力値が、コマンド引数、ログ、MCP メッセージに含まれることはありません。これらのプロンプトには、ローカルで対話可能な TTY が必要です。非 TTY の自動化では、事前に OS のキーチェーンにエントリを用意し、メタデータのみを扱うコマンドを実行してください。CLI は標準入力からシークレットを読み込んだり、平文に暗黙的にフォールバックしたりしません。

CLI で別のメタデータレジストリを選択するには、CLI の実行前に HAPPY_CONFIG_PATH をエクスポートします。

export HAPPY_CONFIG_PATH="$HOME/.config/happy-platform-mcp/instances.json"
happy-platform-mcp instance list

MCP サーバー／stdio ホストでは、ホスト環境に同じ変数を設定します。

{
  "env": {
    "HAPPY_CONFIG_PATH": "~/.config/happy-platform-mcp/instances.json"
  }
}

HAPPY_CONFIG_PATH は ~ と相対パスに対応しています。移行については、パッケージのレガシー形式からユーザーレジストリへの自動移行が利用できるのは、リゾルバーがパッケージ相対パスの config/servicenow-instances.json を readPath として、これと異なるデフォルトのユーザーレジストリを writePath として選択した場合のみです。通常、HAPPY_CONFIG_PATH は readPath と writePath の両方を選択するため、メタデータのみを含むバージョン 1 のレジストリを指定する必要があります。平文のソース（同じファイル）を指定した場合、CLI はキーチェーンへの書き込み前に処理を拒否します。ソースのバイト列とキーチェーンのエントリは変更されません。異なるターゲットを指す HAPPY_CONFIG_PATH を選択するか、自動ワークフローを使用するには設定を解除してください。シークレットをコマンド引数にコピーしないでください。パッケージ以外のレガシーソースには、管理された異なるソース／ターゲットを使うワークフローを使用するか、instance add とマスクされた instance credential set プロンプトを手動で使用してください。

SN-Register-Instance は通常、レジストリのライブ再読み込みを適用するため、再起動は不要です。MCP サーバーの再起動が必要なのは、ドキュメントのみのモードの場合、または再読み込みに失敗した場合だけです。

レガシー互換性： config/servicenow-instances.json は、読み取り専用のレガシー移行入力です。単一の SERVICENOW_* 環境変数は、レジストリを利用できない場合に限り、後方互換性を保つための単一インスタンス用フォールバックとして使用されます。パッケージ相対パスのファイルは、CLI の書き込み先ではありません。

オプション B：単一インスタンス（レガシー環境変数フォールバック）

cp .env.example .env
# Server/stdio only: set legacy SERVICENOW_* variables in .env.

サーバーの起動

# Stdio transport (for Claude Desktop); no HTTP token involved
npm run stdio

# HTTP/SSE transport; refuses to start without a valid bearer token
export HAPPY_MCP_API_TOKEN="$(openssl rand -hex 32)"
npm run dev

HTTP トランスポートのセキュリティ

HTTP/SSE トランスポートは、単一の信頼された運用者、つまり単一の主体向けに構築されています。HAPPY_MCP_API_TOKEN を持つ人は、サーバーに設定されたすべての ServiceNow 認証情報を使用できるため、それらのアカウントで何ができるかは引き続き ServiceNow の ACL によって決まります。HTTP 認証は ACL に取って代わるものではありません。複数ユーザーでの共有ホスティングには対応していません。複数のユーザーやテナントが 1 つのサーバーまたはトークンを共有しても、ユーザーごとの識別、分離、認可は行われません。運用者ごとにサーバーを 1 つ実行してください。

• すべてのリスナーでトークンが必要です。 HAPPY_MCP_API_TOKEN が、64 桁の 16 進数（openssl rand -hex 32）または 43 文字の base64url でエンコードされた 32 個のランダムバイトでない場合、HTTP の起動に失敗します。ループバックや埋め込みの createHttpApp の使用も例外ではありません。サーバーはエンコード形式を確認しますが、ランダム性は測定できないため、必ず値を生成してください。シークレットストアまたは追跡対象外の .env に保管し、コミットやログへの記録は絶対に避けてください。ローテーションするには、新しい値で再起動してください。stdio では使用しません。
• すべてのルートで認証が必要です。 /health、/instances、GET /mcp、POST /mcp はすべて、Authorization: Bearer <token> ヘッダーが正確に 1 つ必要です。トークンは一定時間で比較されます。リクエストは、本文の解析やセッションの設定より前に拒否されます。
• 認証失敗はスロットリングされます。 1 分間に同じ接続元アドレスから 10 回認証に失敗すると、その接続元には期間が終了するまで Retry-After を付けて 429 が返されます。スロットリングはトークンの確認前に行われるため、ブロックされた接続元は正しいトークンを使っても拒否されます。制限値はプロセスのメモリ上に保持されます。再起動するとリセットされ、プロセス間では共有されず、追跡する接続元数にも上限があります。リバースプロキシの背後や、ホストのクライアントが 1 つのゲートウェイアドレスを共有する Docker のポート公開環境では、すべてのクライアントが同じ制限値を共有します。そのため、エンドポイントに到達できる未認証のクライアントは、1 分間に 10 回の不正なリクエストを送るだけで運用者を締め出せます。プロキシに到達できるユーザーを制限し、そこでレート制限を行ってください。
• Host と Origin を確認します（DNS リバインディング対策）。 Host はリスナーを示す必要があります（ループバックの場合は 127.0.0.1:<port>、localhost:<port>、または [::1]:<port>。それ以外の場合は、バインドされたアドレスとポート）。または、HAPPY_MCP_ALLOWED_HOSTS のエントリと完全に一致する必要があります。ネイティブ MCP クライアントが送信するように Origin がないリクエストは許可されます。Origin がある場合は、HAPPY_MCP_ALLOWED_ORIGINS のエントリと完全に一致する必要があります。null、ワイルドカード、不正な値、重複した値は拒否されます。X-Forwarded-* と Forwarded ヘッダーは一切信頼されません。
• リソース制限。 SSE セッションは、保留中が 16 件、アクティブが 32 件までです（超過時は 429）。HEAD /mcp は 405 になります。セッションの設定タイムアウトは 30 秒、アイドルタイムアウトは 30 分、最長有効期間は 12 時間です。JSON 本文の上限は 8 MiB です。各セッションで同時に処理される POST は 1 件、キューには最大 8 件まで保持できます。全セッションを通じて同時に処理される POST は最大 8 件です。応答されていない JSON-RPC リクエストは、セッションごとに最大 16 件、プロセス全体で最大 64 件です。キャンセルされたリクエストは、そのハンドラーが実際に終了するまでスロットを使い続けます。また、ツールハンドラーはキャンセルされても処理を早期終了しないため、遅れて届いた結果は破棄されます。不明なセッション ID や終了済みのセッション ID は拒否されます。

変数	デフォルト	用途
HAPPY_MCP_API_TOKEN	なし（HTTP では必須）	Bearer トークン：64 桁の 16 進数または 43 文字の base64url
HAPPY_MCP_BIND_HOST	127.0.0.1	リッスンアドレス
HAPPY_MCP_ALLOWED_HOSTS	空	リバースプロキシ名など、追加の host[:port] 権限をカンマ区切りで指定します。スキーム、パス、ワイルドカードは指定できません
HAPPY_MCP_ALLOWED_ORIGINS	空（すべての Origin を拒否）	https://console.example.com など、ブラウザーのオリジンを完全一致でカンマ区切りに指定します

リバースプロキシ

プロキシで TLS を終端し、ループバックリスナーに転送します。プロキシが Host をアップストリームアドレス（nginx のデフォルトの $proxy_host。これは 127.0.0.1:3000 になります）に書き換える場合、追加の設定は不要です。公開名を転送する場合は、そのオーソリティを正確に許可してください。

location / {
  proxy_pass http://127.0.0.1:3000;
  proxy_set_header Host $host;   # forwards "mcp.example.com"
  proxy_http_version 1.1;
  proxy_buffering off;           # required for SSE
  proxy_read_timeout 1h;
}

HAPPY_MCP_ALLOWED_HOSTS=mcp.example.com

プロキシは Authorization ヘッダーを変更せずに通過させる必要があります。クライアントのトークンの代わりに、プロキシ独自の認証情報を追加させないでください。

既存の HTTP クライアントの移行

このリリースでは、ループバックを含むすべての HTTP 利用でベアラートークンが必要です。

• curl とスクリプト： /health を含むすべてのリクエストに -H "Authorization: Bearer $HAPPY_MCP_API_TOKEN" を追加します。
• MCP SSE クライアント： SSE の GET リクエストとメッセージの POST リクエストの両方で、クライアントがヘッダーを送信するように設定します。TypeScript SDK では、new SSEClientTransport(url, { requestInit: { headers: { Authorization: 'Bearer ' + token } } }) のようにします。
• Origin を送信するクライアント（Web ビューや、Origin を転送するプロキシなど）：そのオリジンを正確に HAPPY_MCP_ALLOWED_ORIGINS に追加します。サーバーは CORS ヘッダーを送信しないため、クロスオリジンのブラウザーページは引き続きレスポンスを読み取れません。
• Docker： 実行時に HAPPY_MCP_API_TOKEN を指定し、HAPPY_MCP_ALLOWED_HOSTS をクライアントが使用するオーソリティに設定します。例：localhost:3000,127.0.0.1:3000。ヘルスチェックにも認証が必要です。イメージの HEALTHCHECK と docker-compose.yml では、すでに認証が行われます。docs/DOCKER_DEPLOYMENT.md を参照してください。

確認

curl -H "Authorization: Bearer $HAPPY_MCP_API_TOKEN" http://localhost:3000/health
curl -H "Authorization: Bearer $HAPPY_MCP_API_TOKEN" http://localhost:3000/instances

# Without the token the server answers 401
curl -i http://localhost:3000/health

複数インスタンスへのルーティング

すべての稼働中の ServiceNow 操作は、SN-Set-Instance、SN-Get-Current-Instance、SN-Docs-* を除き、省略可能な instance パラメーターを受け付けます。省略すると、現在のセッションクライアントの暗黙的なターゲットが使用されます。対象が異なる複数のインスタンスにまたがる可能性がある場合や、SN-Set-Instance と競合する可能性がある場合は、明示的なルーティングが必要です。同じ安定した暗黙的ターゲットに対する並行呼び出しでは不要です。明示的な呼び出しはインスタンス名でキャッシュされるため、同じ名前のインスタンスへの呼び出しは同じクライアントを共有します。

stdio の起動時に SERVICENOW_INSTANCE が設定されている場合は、名前付きの JSON エントリが選択されます。設定されていない場合は、"default": true とマークされたエントリが使用され、該当するエントリがない場合は、設定されている最初のエントリが使用されます。HTTP セッションでは、設定されたデフォルトのエントリ、または最初のエントリが使用されます。JSON ファイルがない場合は、ServiceNow の環境認証情報を単一のフォールバックインスタンスとして使用できます。"default": true フラグは起動時の設定です。SN-Set-Instance は現在のセッションクライアントをメモリー上で変更するだけで、設定ファイルは編集しません。新しい MCP セッションまたはサーバーは、再び起動時の選択から開始します。

// Uses this session client's current implicit target
await client.callTool({
  name: 'SN-Query-Table',
  arguments: { table_name: 'incident', limit: 10 }
});

// Safely query dev and prod concurrently
await Promise.all([
  client.callTool({
    name: 'SN-Query-Table',
    arguments: { table_name: 'incident', instance: 'dev', limit: 10 }
  }),
  client.callTool({
    name: 'SN-Query-Table',
    arguments: { table_name: 'incident', instance: 'prod', limit: 10 }
  })
]);

ツールの概要

カテゴリ	ツール数	説明
汎用 CRUD	7	任意のテーブルに対するクエリ、作成、取得、更新
ITSM 特化	8	インシデント、変更、問題に関する便利なラッパー
便利機能	10	コメント追加、作業メモ追加、割り当て、解決、クローズ
自然言語	1	平易な英語でクエリを実行
更新セット	6	更新セットの設定、一覧表示、移動、複製、確認
スクリプト	2	バックグラウンドスクリプトの実行、修正スクリプトの作成
ATF テスト	5	CI/CD REST API 経由で ATF テストとスイートを実行し、進行状況を確認して、結果とログを読み取る
スクリプト同期	3	スクリプトをローカルファイルと同期、監視モード
ワークフロー	4	ワークフロー、アクティビティ、トランジションの作成
バッチ	2	テーブルをまたいだ作成・更新のバッチ処理
スキーマ	3	テーブルスキーマ、フィールド情報、リレーションシップ
サービスカタログ	4	カタログフォームの閲覧、確認、送信
ServiceNow ドキュメント	5	公式 ServiceNowDocs の Markdown の検索、同期、検索、取得
リソース	8	テーブル一覧、フィールド情報の読み取り専用 URI

例

以下のトランスポートに依存しない例では、MCP ツール名とその引数を示します。

SN-Query-Table
{ "table_name": "incident", "query": "active=true^priority=1", "limit": 10 }

SN-Create-Incident
{ "short_description": "Email service down", "urgency": 1 }

SN-NL-Search
{ "table_name": "incident", "query": "high priority incidents assigned to me" }

SN-Execute-Background-Script
{ "script": "gs.info('Hello');" }

SN-Set-Update-Set
{ "update_set_sys_id": "abc123..." }

SN-Batch-Update
{ "updates": [{ "table": "incident", "sys_id": "id1", "data": { "state": 2 } }] }

SN-Catalog-Search-Items
{ "keyword": "VPN access" }
SN-Catalog-Get-Item
{ "sys_id": "<catalog_item_sys_id>" }
SN-Catalog-Submit
{ "sys_id": "<catalog_item_sys_id>", "variables": { "requested_for": "jsmith", "justification": "Project X" } }

SN-Run-ATF-Suite
{ "test_suite_name": "Smoke Tests", "timeout_seconds": 45 }
SN-Get-ATF-Test-Logs
{ "result_id": "<sys_atf_test_result sys_id>", "pattern": "error|fail" }

SN-Docs-Families
{}
SN-Docs-Sync
{ "family": "australia" }
SN-Docs-Search
{ "query": "create a Flow Designer action", "family": "australia" }

ローカルでのスクリプト開発

バージョン管理と自動同期を利用して、スクリプトをローカルで開発します。

SN-Sync-Script-To-Local
{
  "script_sys_id": "abc123...",
  "local_path": "/scripts/business_rules/validate_incident.js"
}

SN-Watch-Script
{
  "local_path": "/scripts/business_rules/validate_incident.js",
  "script_sys_id": "abc123..."
}

自然言語検索

SN-NL-Search
{
  "table_name": "incident",
  "query": "active high priority incidents that are unassigned"
}

フィールド比較、テキスト検索、日付範囲、論理演算子、並べ替えなど、15種類以上のパターンに対応しています。

ServiceNow ドキュメント検索

Happy MCP は、GitHub から公式の ServiceNowDocs マークダウンを直接取得できます。また、ドキュメントのファミリーを SQLite FTS5 インデックスにローカルで登録して、高速なローカル検索を行うこともできます。ローカルインデックスはデフォルトで無効です。有効にするには、バージョン 1 のレジストリで docs.localIndexEnabled=true を設定するか、HAPPY_DOCS_ENABLE_LOCAL_INDEX=true を設定してください。

SN-Register-Instance
{ "name": "dev", "url": "https://your-instance.service-now.com", "username": "your-username" }

SN-Docs-Families
{}
SN-Docs-Status
{}
SN-Docs-Sync
{ "family": "australia" }
SN-Docs-Search
{ "query": "update set best practices", "family": "australia", "limit": 5 }
SN-Docs-Get
{ "family": "australia", "path": "platform/example.md" }

SN-Register-Instance が受け付けるのはメタデータのみです。パスワード、 クライアントシークレット、その他のシークレットフィールドは受け付けません。必須のローカル認証情報が 不足している場合、レスポンスにはローカルで実行する正確な happy-platform-mcp instance credential set ... コマンドが表示されます。登録によってメタデータは永続化されますが、 ドキュメント専用サーバーで ServiceNow のライブツールを有効にするには、サーバーを再起動する必要があります。

SQLite のローカルインデックスは任意で、デフォルトでは無効です。ベクトル検索も任意です。ローカルインデックスを有効にし、HAPPY_DOCS_ENABLE_VECTOR=true を設定してから、HAPPY_DOCS_EMBEDDING_PROVIDER=local を指定すると、決定的なローカル埋め込みを使用した sqlite-vec インデックスを構築できます。ServiceNow Docs Search を参照してください。

ServiceNow の認証情報がないドキュメント専用のデプロイでは、HAPPY_MCP_DOCS_ONLY=true を設定してください。設定ファイルも ServiceNow の環境認証情報も存在しない場合、stdio サーバーは自動的にドキュメント専用モードに切り替わります。

実行時のインスタンス選択

登録と実行時の選択は別々です。

• 登録すると、使用可能な名前付きインスタンスがレジストリに永続化されます。
• SERVICENOW_INSTANCE が選択するのは、stdio 起動時のデフォルトのみです。
• SN-Set-Instance は、順次処理されるセッションで共有される暗黙のターゲットをメモリ上で変更します。レジストリは編集しません。
• オプションの呼び出しごとの instance 引数は、分離されたリクエストターゲットを選択します。これにより、順次処理のターゲットを競合させることなく、並行呼び出しを異なるインスタンスにルーティングできます。

Claude Desktop の統合

~/Library/Application Support/Claude/claude_desktop_config.json に追加します。

グローバルインストールでは、引数を指定せずに起動すると stdio が使用されます。

{
  "mcpServers": {
    "happy-mcp-server": {
      "command": "happy-platform-mcp",
      "env": { "SERVICENOW_INSTANCE": "dev" }
    }
  }
}

一時インストールでは、command: "npx" と args: ["-y", "happy-platform-mcp"] を使用します。

{
  "mcpServers": {
    "happy-mcp-server": {
      "command": "npx",
      "args": ["-y", "happy-platform-mcp"],
      "env": {
        "HAPPY_CONFIG_PATH": "~/.config/happy-platform-mcp/instances.json"
      }
    }
  }
}

レジストリ設定が指すのはメタデータです。認証情報はローカル OS の キーチェーンに保存されます。デフォルトのユーザーパスを使用する場合、HAPPY_CONFIG_PATH は任意です。サーバーの起動前に設定する必要があります。ソースからインストールした場合は、ホストの設定で node src/stdio-server.js を使用し、CLI 操作では node src/cli.js instance <command> を使用します。設定を編集した後は、Claude Desktop を再起動してください。

認証

Happy MCP Server は、インスタンスごとに 3 種類の認証情報フローに対応しています。対話形式の instance add では、各必須シークレットを一度入力すると、OS のキーチェーンに保存され、メタデータが登録されます。instance credential set は、既存の認証情報をローテーションする場合、またはメタデータのみの MCP 登録を完了する場合に限り、後から使用してください。シークレットを JSON やコマンド引数に含めないでください。

グローバル CLI：dev の基本認証

happy-platform-mcp instance add
# Select Basic authentication; set the name to dev, enter URL and username,
# then enter the masked password when prompted. The command stores it once.
happy-platform-mcp instance test dev

グローバル CLI：prod の OAuth クライアント認証情報

happy-platform-mcp instance add
# Select OAuth -> Client credentials; set the name to prod, enter URL and
# client ID, then enter the masked client secret. The command stores it once.
happy-platform-mcp instance test prod

OAuth パスワードグラント

happy-platform-mcp instance add
# Select OAuth -> Password grant; enter URL, client ID, and username, then
# enter both masked prompts. The command stores both credentials once.
happy-platform-mcp instance test password-prod

パスワードグラントの credentialRef は、正規の参照を両方含むオブジェクトである必要があります。

"credentialRef": {
  "password": "keychain:instance/password-prod/password",
  "clientSecret": "keychain:instance/password-prod/client-secret"
}

PKCE を使ったパブリッククライアント認可コードフロー

happy-platform-mcp instance add
# Select OAuth -> Authorization code and enter URL, client ID,
# authorize URL, token URL, redirect port, and callback path.
happy-platform-mcp instance test public-dev

パブリッククライアントの認可コードフローのメタデータでは、credentialRef やクライアントシークレットは必要ありません。最初のテストまたは API 呼び出しでブラウザーフローが開始され、リフレッシュトークンが OS のキーチェーンに保存されます。

リフレッシュトークンは、OAuth ID（ローカル OS ユーザー、正規化されたインスタンス URL、クライアント ID、有効な認可／トークンエンドポイント）をキーとして管理されます。インスタンス名はキーに含まれないため、名前を変更してもサインイン状態は維持されます。また、同じ名前のインスタンスでも、別の URL、クライアント、IdP の場合はそのトークンを受け取りません。**アップグレード後は、認可コードフローを使うインスタンスごとに 1 回サインインしてください。**以前の名前をキーとしたトークンは読み込まれず、移行もされません。新しいサインインが成功すると削除されます。 instance remove および instance update で URL、クライアント ID、認可 URL、トークン URL を変更すると、レジストリを変更する前に、その ID のリフレッシュトークン（および従来の名前をキーとしたエントリ）が、サーバーが使用した OS のキーチェーンとファイルトークンストアの両方から削除され、削除したストアが表示されます。いずれかのストアでエラーが報告されると、コマンドはレジストリを変更する前に停止します。Windows では、ディレクトリが存在しない場合にのみファイルストアがスキップされます。レジストリファイルを手動で編集してもトークンは削除されません。その場合、古いトークンが別の ID に使用されることはありません。

キーチェーンバインディング（@napi-rs/keyring 2.1 以降）は、キーチェーンがロック中、アクセス拒否、またはアクセス不能の場合に「エントリなし」ではなくエラーを報告します。そのため、削除を完了できない場合、レジストリを変更する前にコマンドが停止します。キーチェーンのロックを解除してから再試行してください。キーチェーンのエラーには、「キーチェーンのバックエンドがない」状態と「ロック中」の状態を区別するコードが含まれないため、キーチェーンが利用できない場合は常にコマンドが停止します。Secret Service がない Linux では、このバインディングはカーネルキーリングにフォールバックします。どちらも機能しない環境（たとえば、keyctl がブロックされているコンテナー）では、サーバーが使用できるのはファイルストアのみです。$XDG_CONFIG_HOME/happy-platform-mcp/（または ~/.config/happy-platform-mcp/）内の token-* ファイルと、レジストリファイル内のインスタンスエントリを手動で削除してください。

信頼された外部 ID プロバイダー

認可エンドポイントとトークンエンドポイントのデフォルトはインスタンス自体です（/oauth_auth.do、/oauth_token.do）。インスタンスと同じオリジンにあるカスタムエンドポイントは常に許可されます。外部 IdP は、設定を読み込むすべてのプロセス（MCP サーバー および happy-platform-mcp instance … を実行するシェル。CLI は .env を読み込みません）の環境に、その正確なオリジンが指定されている場合にのみ受け入れられます。

export SERVICENOW_OAUTH_TRUSTED_ORIGINS=https://login.example.com,https://idp.example.net:8443

エントリはパス、クエリ、フラグメント、認証情報、ワイルドカードを含まない HTTPS オリジンである必要があります（ローカルテストではループバックの HTTP が許可されます）。形式が不正なエントリは拒否されます。許可リストは、インスタンスレジストリや MCP ツールから設定できません。インスタンスの登録時または読み込み時、および各トークンリクエストの直前にチェックされます。トークンリクエストでリダイレクトが追従されることはありません。すでに外部 IdP を使用しているレジストリは、そのオリジンが追加されるまでサーバーでも CLI のすべてのコマンド（instance remove を含む）でも読み込みに失敗します。サーバーがカスタムの XDG_CONFIG_HOME でファイルトークンストアを使用している場合は、削除対象のディレクトリが一致するよう、CLI にも同じ XDG_CONFIG_HOME を設定してください。

プレーンテキストでのリフレッシュトークン保存（POSIX のみ）

OS のキーチェーンが引き続きデフォルトです（未設定、または SERVICENOW_TOKEN_STORE=keychain）。 認可コードのリフレッシュトークンをプレーンテキストの token-<sha256-hex> ファイルとして保存するには、サーバープロセスの環境で SERVICENOW_TOKEN_STORE=file を明示的に指定してください。ファイル名にはアカウントキーの SHA-256 が使われるため、大文字と小文字を区別しないファイルシステムでも、大文字と小文字だけが異なるアカウントが同じファイルを参照することはありません。保存先は $XDG_CONFIG_HOME/happy-platform-mcp、または XDG が未設定の場合は ~/.config/happy-platform-mcp です。以前の token-<account> ファイルは読み込まれません。再認可してください。XDG_CONFIG_HOME には、信頼できる絶対パスを指定する必要があります。インスタンスのパスワードや OAuth クライアントシークレットのキーチェーン保存方法は変わりません。

ファイルストアでは、現在のユーザーが所有すること、ディレクトリが非公開の 0700 であること、トークンファイルが通常ファイルで 0600 であることを確認します。安全でない既存のディレクトリやファイル、シンボリックリンク、信頼できないユーザーが書き込み可能な上位ディレクトリ、セットアップや権限のエラーがある場合は、処理を安全側に倒して拒否します。ディレクトリを作成する前に、既存のすべての上位ディレクトリ（シンボリックリンクの解決後）を確認します。これらは現在のユーザーまたは root が所有し、スティッキービットが設定されていない限り、グループまたはその他のユーザーが書き込み可能であってはなりません。エラーには、該当するパスと必要な所有者・モードが示されます。ディレクトリにすでに、より広い権限で設定情報が保存されている場合は、内容を確認し、このオプションを有効にする前に非公開にしてください。サーバーが、公開状態にある既存のストレージを暗黙に修復することはありません。Windows のファイルモードビットでは Windows ACL によるプライバシーを強制できないため、Windows ではファイルストレージを拒否します。OS キーチェーンのデフォルトを使用してください。詳しくはセットアップの詳細を参照してください。

同じ OS ユーザーで実行されるプロセスであれば、誰でもこれらのプレーンテキストトークンを読み取れます。このディレクトリを共有・同期バックアップの対象から除外するか、バックアップをシークレットとして保護してください（アクセス制御と暗号化を含みます）。内容をコミット、ログ出力、アップロードしないでください。ストアを切り替えてもトークンは移行されません。選択したストアで再認可してください。書き込みには、固有の排他的な 0600 の一時ファイルと、同一ディレクトリ内でのアトミックな名前変更を使用します。これにより、同時に書き込むプロセスが一時ファイルを共有せず、読み取り側には完全なトークンが見えます。ただし、OAuth のリフレッシュ処理の直列化、プロセス間でのリフレッシュトークンのローテーションへの対応、電源喪失時の永続性は保証しません。ID ごとにリフレッシュ処理を行うプロセスは 1 つだけ使用してください。

アーキテクチャ

src/
├── server.js                     # Express HTTP server (SSE transport)
├── stdio-server.js               # Stdio transport (Claude Desktop)
├── mcp-server-consolidated.js    # MCP tool registration & routing
├── servicenow-client.js          # REST API client
└── config-manager.js             # Multi-instance configuration

config/
└── servicenow-instances.json     # Instance configuration

docs/
├── API_REFERENCE.md              # Complete tool reference
├── SETUP_GUIDE.md                # Detailed setup instructions
└── research/                     # Technical research & discoveries

テスト

# Run tests
npm test

# Watch mode
npm run test:watch

# Coverage
npm run test:coverage

# MCP Inspector
npm run inspector

トラブルシューティング

接続の問題

# Test configured credentials without exposing them in shell history.
happy-platform-mcp instance test <instance-name>

# Check server health (HTTP transport)
curl -H "Authorization: Bearer $HAPPY_MCP_API_TOKEN" http://localhost:3000/health

よくある問題

• 複数インスタンスが機能しない： バージョン 1 のレジストリが有効な JSON であり、起動時のデフォルトが必要な場合に "default": true のインスタンスが 1 つあることを確認してください。通常の稼働中の登録は再起動なしで再読み込みされます。再起動が必要なのは、ドキュメントのみのモードの場合、または再読み込みに失敗した場合だけです。
• ツールが表示されない： MCP Inspector の接続とサーバーログを確認してください。
• 認証の失敗： happy-platform-mcp instance test <instance-name> を実行し、ローカルのキーチェーン資格情報の参照先と、必要な ServiceNow ロールを確認してください。
• HTTP 401／403／429： 401 はベアラートークンの欠落、重複、または誤りを示します。403 は Host または Origin ヘッダーが許可されていないことを示します（HTTP トランスポートのセキュリティを参照）。429 は、接続元からの認証失敗が多すぎるか、開いているセッションが多すぎることを示します。Retry-After を待ってください。
• Docker で SSE が切断される： キープアライブを有効にしてください（デフォルトは 15s）。docs/SSE_DOCKER_SETUP.md を参照してください。

デバッグモード

DEBUG=true npm run dev

既知の制限事項

• Flow Designer のロジックブロックは REST API 経由では作成できません（UI を使用してください）
• フローのコンパイル／検証は UI で行う必要があります
• UI Policy Actions のリンクには、バックグラウンドスクリプトによる回避策が必要です

詳しくは、API リファレンスと docs/ 内のツール別ガイドを参照してください。

謝辞

このプロジェクトは、Echelon AI Labs ServiceNow MCP Serverに着想を得ています。ServiceNow® プラットフォームに MCP の機能をもたらした先駆的な取り組みに感謝します。

コントリビューション

ガイドラインについてはCONTRIBUTING.mdを参照してください。すべてのコントリビューターは CLA に署名する必要があります。

セキュリティ

脆弱性を報告するには、SECURITY.mdをご覧ください。セキュリティに関する問題を公開のイシューとして投稿しないでください。

ライセンス

Apache License 2.0に基づいてライセンスされています。

Copyright 2025 Happy Technologies LLC

---

商標に関するお知らせ

ServiceNow®はServiceNow, Inc.の登録商標です。「Now」はServiceNow, Inc.の登録商標です。すべてのServiceNow®製品名、ロゴ、ブランドはServiceNow, Inc.の所有物です。

Model Context Protocol（MCP）はAnthropic, PBCが作成したオープン標準です。「Claude」はAnthropic, PBCの商標です。

Happy MCP Serverは、独立したコミュニティ主導のプロジェクトです。 ServiceNow, Inc.またはAnthropic, PBCとの提携、承認、支援を受けていません。このプロジェクトは、公開されているREST APIを介してServiceNow®インスタンスに接続するツールを提供し、オープンなMCP仕様を実装しています。ServiceNow®の製品やサービスと競合するものではありません。

その他すべての商標は、それぞれの所有者に帰属します。クレジット表記の詳細はNOTICEをご覧ください。