SN-MCP-Server

📘 SN-MCP-Server

ServiceNow 向けの読み取り専用 Model Context Protocol（MCP）サーバーです。開発者、AI ワークフロー、および ServiceNow の複数のインスタンス（Prod、Dev、Test、PDI）を詳細に把握する必要があるツール向けに構築されています。

---

✨ 特長

• 🔗 複数インスタンス対応 — 1 つのサーバーで Prod、Dev、Test、PDI を利用できます
• 🔍 強力なクエリ機能 — Table、Aggregate、Code Search API
• 🧠 インテリジェントなレコード解決 — INC、CHG、RITM、sys_id
• 🔄 Flow Designer + レガシーワークフロー
• 🧩 スキーマの検査と検出
• 👥 ID およびアクセスデータ
• 🔑 複数の認証方式 — Basic Auth と OAuth 2.0（Client Credentials、Password、Auth Code、JWT）
• 🧰 ServiceNow SDK のサポート — now-sdk がグローバルにインストールされている場合（npm install -g now-sdk）、オプションの sn_sdk_explain ツールが登録されます
• 設計上、読み取り専用 — 本番インスタンスでも安全に使用できます
• 📄 実行ごとのログファイル — サーバーの起動ごとに 1 つのファイルを OS の一時フォルダーに保存します
• 🔬 詳細なツールログ — SN_MCP_VERBOSE=true の場合、呼び出しごとのデバッグ行（インスタンス、引数、結果の概要）を記録します
• 📚 ServiceNow ドキュメント検索 — sn_read_docs は ServiceNowDocs リポジトリを検索し、直接読み込むための file_path／raw_url を返します。また、デフォルト以外のバージョンが指定された場合は、選択されたブランチを解決できます

---

🚀 クイックスタート

オプション A — npx（インストール不要）

npx @imjaineel-dev/sn-mcp-server --config ./sn-instance.json

オプション B — ローカルクローン

git clone https://github.com/ImJaineel/SN-MCP-Server.git
cd SN-MCP-Server
npm install
npm start   # auto-detects sn-instance.json in repo root

---

⚙️ 設定

1. sn-instance.json を作成する

{
  "default": "dev",
  "instances": [
    {
      "alias": "prod",
      "label": "Production",
      "instance": "mycompany-prod",
      "auth": "oauth2",
      "grant_type": "client_credentials",
      "client_id": "your-client-id",
      "client_secret": "your-client-secret"
    },
    {
      "alias": "dev",
      "label": "Development",
      "instance": "mycompany-dev",
      "auth": "basic",
      "username": "svc_mcp_readonly",
      "password": "your-password-here"
    }
  ]
}

📄 完全な例：sn-instance.example.json

共通フィールド

フィールド	必須	説明
alias	✅	ツール呼び出しで使用する短い名前（"prod"、"dev-2"）
instance	✅	サブドメイン（"mycompany-dev"）または完全な URL（"https://..."）
auth	任意	"basic"（デフォルト）または "oauth2"
label	任意	人が読みやすい表示名
default	任意	トップレベルの "default" エイリアス、または各エントリーの "default": true のいずれかを指定して、デフォルトのインスタンスを選択します

Basic Auth（auth: "basic"）

フィールド	必須	説明
username	✅	サービスアカウントのユーザー名
password	✅	パスワードまたは API トークン

OAuth 2.0（auth: "oauth2"）

フィールド	必須	説明
grant_type	✅	"client_credentials"、"password"、"authorization_code"、または "jwt_bearer"
client_id / client_secret	✅	OAuth アプリケーションの認証情報
username / password	条件付き	password グラントで必須
refresh_token	条件付き	authorization_code グラントで必須
jwt_private_key / jwt_subject	条件付き	jwt_bearer グラントで必須（PEM キー文字列とサブジェクトユーザー）
jwt_issuer	任意	jwt_bearer グラントの任意の発行者値
token_url	任意	デフォルトのトークンエンドポイントを上書きします（デフォルト：/oauth_token.do）

デフォルトの選択は、次の順序で解決されます。

1. 設定オブジェクト内に明示的に指定されたトップレベルの "default" エイリアス
2. "default": true のエントリー
3. リストの最初のエントリー

---

2. 環境変数（任意）

すべて任意です。シェル、MCP クライアントの "env" ブロック、またはプロジェクトルートの .env ファイルで設定してください。シェルの値は .env より優先されます。

注： ローカルクローンからサーバーを実行する場合、ルートレベルの .env ファイルは起動時に自動的に読み込まれます。

変数	説明	デフォルト
SN_INSTANCE_CONFIG	sn-instance.json へのパス	自動解決
SN_MCP_VERBOSE	デバッグログを有効にするには "true" に設定します	false
LOGS_TIMEZONE	ログのタイムスタンプに使用する IANA タイムゾーン（CURRENT、GLOBAL、または名前付きタイムゾーン）	CURRENT
SN_LOG_DIR	ログファイルのディレクトリを上書きします	OS の一時フォルダー
GITHUB_TOKEN	sn_read_docs 用の GitHub Personal Access Token（ブランチの検索と GitHub 検索）	なし

環境変数の代わりに CLI フラグも使用できます。

• --config <path> → SN_INSTANCE_CONFIG を設定します
• --verbose → SN_MCP_VERBOSE=true を設定します
• --github-token <token> → GITHUB_TOKEN を設定します

---

🔌 MCP クライアントのセットアップ

すべてのユーザー向け

VS Code： Ctrl+Shift+P を押し、Add MCP を選択します

Claude Desktop： ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）または %APPDATA%\Claude\claude_desktop_config.json（Windows）を編集します

Gemini Code Assist： ~/.gemini/mcp.json を作成または編集します

Amazon Q： ~/.aws/amazonq/mcp.json を作成または編集します

npx を使用する場合（推奨）：

{
  "mcpServers": {
    "servicenow": {
      "command": "npx",
      "args": ["sn-mcp-server", "--config", "/absolute/path/to/sn-instance.json"],
    }
  }
}

ローカルクローンを使用する場合：

{
  "mcpServers": {
    "servicenow": {
      "command": "node",
      "args": ["/absolute/path/to/SN-MCP-Server/src/index.js"]
    }
  }
}

⚠️ MCP クライアントの設定では、必ず絶対パスを使用してください。

---

▶️ ローカルでの実行

# Standard start (auto-detects ./sn-instance.json)
npm start

# With explicit config path
node src/index.js --config /path/to/sn-instance.json

# With verbose logging
npm run dev
node src/index.js --config ./sn-instance.json --verbose

# Auto-restart on file changes (development)
npm run watch

# Open MCP Inspector UI in browser (test tools interactively)
npm run inspect
# The inspector launcher accepts localhost and 127.0.0.1 origins so the browser can connect reliably.

# Show help
npx sn-mcp-server --help

---

🪵 ログ

サーバーを実行するたびに、新しいタイムスタンプ付きログファイルが作成されます。

2026-04-09T14-32-01.123Z.log

OS の一時ディレクトリに保存されます。

OS	デフォルトのログ保存場所
Windows	%TEMP%\ImJaineel_SN-MCP-Instance_logs\
macOS	$TMPDIR/ImJaineel_SN-MCP-Instance_logs/
Linux	/tmp/ImJaineel_SN-MCP-Instance_logs/

SN_LOG_DIR 環境変数で上書きできます。ログファイルは OS の再起動時に自動的に削除されます。

起動バナーには、ログファイルの正確なパスが常に表示されます。

Log file : /tmp/ImJaineel_SN-MCP-Instance_logs/2026-04-09T14-32-01.123Z.log

---

🧰 利用可能なツール

現在の環境でサポートされている場合、サーバーは実行時に16 個のツールを公開します。

• 14 個のインスタンスツール — sn-instance.json の設定が必要です
• 2 個のナレッジツール — ドキュメントと SDK のガイダンスを提供する、インスタンスに依存しないツールです

14 個のインスタンスツール

ツール	説明	表示条件
sn_list_instances	設定済みのすべてのインスタンスと、そのエイリアス、ラベル、URL を一覧表示します。	sn-instance.json が設定され、読み込まれている場合に表示されます。
sn_ping	特定のインスタンス、またはデフォルトのインスタンスへの接続をテストします。	sn-instance.json が設定され、読み込まれている場合に表示されます。
sn_get_identity	ID テーブルからユーザー、グループ、グループメンバーシップを照会します。	sn-instance.json が設定され、読み込まれている場合に表示されます。
sn_inspect_table	テーブルのスキーマを調べるか、名前／ラベルで一致するテーブルを検索します。	sn-instance.json が設定され、読み込まれている場合に表示されます。
sn_aggregate_table	件数、合計、平均、最小値、最大値などの集計クエリを実行します。	sn-instance.json が設定され、読み込まれている場合に表示されます。
sn_query_table	エンコードクエリ、フィールド、ページング、表示値を指定して、任意の ServiceNow テーブルから汎用的な読み取りを行います。	sn-instance.json が設定され、読み込まれている場合に表示されます。
sn_get_record	sys_id、レコード番号、タスクテーブル、CMDB CI クラスを使ってレコードを特定し、取得します。	sn-instance.json が設定され、読み込まれている場合に表示されます。
sn_get_attachment	Attachment API から添付ファイルのメタデータまたはファイルの内容を取得します。	sn-instance.json が設定され、読み込まれている場合に表示されます。
sn_get_update_sets	更新セットを一覧表示するか、特定の更新セット内のファイルを詳しく調べます。	sn-instance.json が設定され、読み込まれている場合に表示されます。
sn_code_search	ServiceNow ネイティブの Code Search API を使ってスクリプトアーティファクトを検索します。	sn-instance.json が設定され、読み込まれている場合に表示されます。
sn_get_scripted_artifacts	Script Includes、Business Rules、Client Scripts、UI Actions、Scheduled Jobs、Fix Scripts、Scripted REST アーティファクトを取得します。	sn-instance.json が設定され、読み込まれている場合に表示されます。
sn_legacy_workflow_search	クラシックワークフローのアクティビティ変数値を検索し、所有するワークフローのバージョンを特定します。	sn-instance.json が設定され、読み込まれている場合に表示されます。
sn_get_legacy_workflow_artifacts	wf_* テーブルからレガシーワークフローのアーティファクトを取得します。	sn-instance.json が設定され、読み込まれている場合に表示されます。
sn_get_workflow_studio_artifacts	sys_hub_* テーブルおよび関連テーブルから Workflow Studio と Flow Designer のアーティファクトを取得します。	sn-instance.json が設定され、読み込まれている場合に表示されます。

2 個のナレッジツール

ツール	説明	表示条件
sn_read_docs	リリースブランチごとに ServiceNowDocs の Markdown を検索、閲覧、読み込みします。検索モードでは直接読み込むための file_path と raw_url の値が返され、get_file は raw GitHub URL またはリポジトリ相対パスを受け付けます。	常に表示されます。
sn_sdk_explain	now-sdk を介して ServiceNow SDK に問い合わせ、SDK のスキル、API、概念について説明を得ます。	now-sdk がインストールされ、正常に実行できる場合にのみ表示されます。

実行時の表示ルール

• **インスタンスツール（14 個）**は、サーバーが 設定なしモード（sn-instance.json が提供されていない状態）で起動すると非表示になります。このモードでは、2 個のナレッジツールのみが表示されます。
• sn_read_docs は、ServiceNow インスタンスの認証情報に依存しないため、常に登録されます。
• sn_sdk_explain は now-sdk のプローブが成功した後にのみ追加されます。パッケージがインストールされていない場合、または実行できない場合、このツールは完全に省略されます。次のコマンドでグローバルにインストールします：npm install -g now-sdk
• 各インスタンスツールは、省略可能な instance パラメーターを受け付けます。省略すると、サーバーは設定済みのデフォルトのインスタンスを使用します。

---

💡 使用例

特定のインスタンスを指定する

sn_get_scripted_artifacts  table="sys_script_include"  query="nameLIKEMorpheus"  instance="prod"
sn_query_table  table="incident"  query="state=1"  instance="dev"
sn_get_update_sets  instance="pdi"

インシデントを照会する

{ "tool": "sn_query_table", "table": "incident", "query": "active=true", "limit": 5 }

ServiceNow Docs を検索する

{ "tool": "sn_read_docs", "mode": "search", "search": "Install the ServiceNow SDK in an application", "version": "australia" }

返された file_path または raw_url を指定して mode": "get_file" を使用し、一致するドキュメントを読み込みます。

番号でレコードを取得する

{ "tool": "sn_get_record", "number": "INC0012345" }

レガシーワークフローを検索する

{ "tool": "sn_legacy_workflow_search", "query": "morpheus", "instance": "prod" }

集計する

{
  "tool": "sn_aggregate_table",
  "table": "incident",
  "aggregates": [{ "field": "priority", "function": "count" }],
  "group_by": ["priority"]
}

---

📁 プロジェクト構成

SN-MCP-Server/
├── src/
│   ├── cli.js            ← npx entrypoint (--config, --verbose, --github-token, --help)
│   ├── index.js          ← server bootstrap and startup banner
│   ├── config.js         ← config path resolution and validation
│   ├── validator.js      ← sn-instance.json schema validation
│   ├── constants.js      ← shared repo/example URLs
│   ├── env-loader.js     ← .env file parser (no external deps)
│   ├── logger.js         ← structured logger, per-run log files
│   ├── multi-client.js   ← multi-instance routing and default-instance resolution
│   ├── sn-client.js      ← per-instance REST client
│   ├── handler.js        ← tool name → method router
│   ├── tools.js          ← MCP tool definitions
│   ├── docs-client.js    ← ServiceNowDocs search/browse/read implementation
│   └── sdk-client.js     ← ServiceNow SDK availability probe and explain helper
├── scripts/
│   ├── dev.js            ← development helper
│   └── inspect.js        ← MCP Inspector launcher with origin allowlist
├── sn-instance.json          ← your credentials (git-ignored)
├── sn-instance.example.json  ← template with supported auth flows
├── .env.example              ← environment variable documentation
├── README.md                 ← full project documentation
└── package.json

---

⚠️ トラブルシューティング

認証情報が無効です

• sn-instance.json のユーザー名とパスワードを確認してください
• ServiceNow でアカウントの REST API アクセスが有効になっていることを確認してください

インスタンスに接続できません

• instance の値の形式（サブドメインまたは完全な URL）を確認してください
• VPN とネットワークの接続を確認してください

sn-instance.json の検証エラー

• サーバーには、該当するフィールドまたはエントリを示す具体的なエラーメッセージが表示されます
• 例を参照してください：sn-instance.example.json

MCP クライアントがサーバーを検出できません

• MCP クライアントの設定では、常に絶対パスを使用してください
• 設定を変更した後は、MCP クライアントを再起動してください

---

🔐 セキュリティに関する注意事項

• sn-instance.json は .gitignore に含まれています。絶対にコミットしないでください
• インスタンスごとに、専用の読み取り専用サービスアカウントを使用してください
• PDI インスタンスは隔離されているため、admin の認証情報を安全に使用できます
• 共有環境では、認証情報を環境変数に保存しないでください

---

🤝 コントリビューション

PR を歓迎します！大きな変更の場合は、まず issue を作成してください。

🐛 バグを報告する

バグが発生した場合は、こちらから GitHub issue を作成してください：

• https://github.com/ImJaineel/SN-MCP-Server/issues/new

迅速に修正できるよう、報告には次の情報を含めてください：

• 期待していた動作
• 実際に発生した動作
• 使用したコマンドまたは MCP クライアントの設定
• 関連するログ出力またはエラーテキスト
• sn-instance.json または .env から、機密情報を伏せた抜粋

---

📄 ライセンス

詳細は LICENSE を参照してください。