```text
/>_________________________________
[########[]_________________________________>
\>
```
# ⛩️ servicenow-mcp ⛩️
### ⚔️ 武士道 (BUSHIDO) エディション ⚔️
[](https://github.com/tedorigawa001/ServiceNow-MCP)
[](docs/TOOLS.md)
[](https://www.npmjs.com/package/@tedorigawa001/servicenow-mcp)
[](https://www.typescriptlang.org/)
[](LICENSE)
[](https://nodejs.org)
[](https://modelcontextprotocol.io)
## AI から ServiceNow を自然言語で操作する MCP サーバー
> **ローカル PC で動作 · 503 ツール · 5 分セットアップ · MIT ライセンス**
Claude・Cursor・VS Code などの AI ツールから、ServiceNow のインシデント・変更・CMDB・スクリプトなどをすべて自然言語で操作できます。
### 開発版（未リリース）
- 明示指定の[AU-CL-006](docs/BEST_PRACTICE_UI_POLICY_CLIENT.md)を追加。Client Scriptのg_formによる必須・表示・読取専用制御をUI Policy検討の候補にします。複雑な処理やUI制約を一律違反とせず、適合性を確認項目として返します。既定3規則・上限は維持、合成検証のみです。
- 明示指定の[AU-CL-002](docs/BEST_PRACTICE_CLIENT_LOOKUPS.md)を追加。Client ScriptのgetReference／GlideRecord get・queryを、受信側を区別した照会確認候補として返します。不要と断定せず、頻度・必要列・業務上の必要性を確認項目にします。実PDI検証は未実施です。
- 明示指定の[AU-CL-008](docs/BEST_PRACTICE_ONCHANGE_LOADING.md)を追加。onChangeのClient Scriptで、読込フラグのガードと照会箇所を区別し、読込時にも必要かを確認する候補として返します。単なるisLoadingへの言及や別イベントを同一視せず、自動return追加はしません。合成検証のみです。
- 明示指定の[AU-CL-003](docs/BEST_PRACTICE_ONLOAD_SCRATCHPAD.md)を追加。onLoadの取得入力を定数・実行時依存・情報不足に分け、可用性・鮮度・公開範囲の確認候補を返します。scratchpad移行を一律推奨せず、機密データ追加や自動移行は行いません。実PDI確認は未実施です。
- 明示指定の[AU-CL-007](docs/BEST_PRACTICE_DOM_CLIENT.md)を追加。Client Scriptの文書由来とcreateElement由来のDOM検索を区別し、標準UIか自作DOMかを決めつけず確認候補を返します。同名の独自メソッドを除外し、受信側不明は未解決として残します。自動削除・置換や実PDI確認は行っていません。
- 明示指定の[AU-CL-005](docs/BEST_PRACTICE_SETVALUE_CLIENT.md)を追加。Client Scriptのg_form由来の2引数setValueを、独自メソッド・3引数呼出しと区別して確認候補にします。参照列・表示値の可用性・追加通信を断定せず、照会追加や引数の自動挿入はしません。実PDI確認は未実施です。
- 明示指定の[AU-QRY-002](docs/BEST_PRACTICE_FULLTEXT_QUERY_BR.md)を追加。BRの2引数addQueryと固定addEncodedQueryの全文検索条件を区別し、索引・検索設定の確認候補を返します。索引の有無・検索可否・違反は断定せず、索引作成やクエリ変更は実行しません。実PDI確認は未実施です。
- 明示指定の[AU-BR-007](docs/BEST_PRACTICE_DISPLAY_WRITE_BR.md)を追加。保存値before_displayのBRでcurrentへの直接書込み・限定setterを確認候補にします。表示目的の変更を違反と断定せず、永続化要件を確認項目として返します。既定3規則・上限は維持、合成検証のみです。
- 明示指定の[AU-BR-005](docs/BEST_PRACTICE_ABORT_ACTION_BR.md)を追加。before BRの中止後の呼出し・プロパティ書込みを、受信側・順序・早期return・if分岐を区別して候補化します。必要な後処理を違反と断定せず、未対応経路は未解決。既定3規則・上限は維持し、合成検証のみです。
- 明示指定の[AU-BR-004](docs/BEST_PRACTICE_TOP_LEVEL_BINDINGS_BR.md)を追加。BRのトップレベル変数候補を関数/ブロックlocalと区別し、共有の意図は確認項目として返します。Global-tableとglobal scopeを混同せず、自動除外や承認はしません。既定3規則は維持、今回の追加分は合成検証のみです。
- `AU-QRY-001`を明示指定する[BR限定のaddQueryレビュー](docs/BEST_PRACTICE_QUERY_LIKE_BR.md)を追加。ローカルGlideRecord系の3引数・リテラル`LIKE`を候補化し、encoded queryのLIKEは対象外。未解決は制限として返します。既定3規則は維持し、今回の追加分は合成検証のみ・PDI未検証です。
- 読み取り専用PoC `review_update_set_best_practices` を登録。AustraliaのUpdate Set payloadを対象に、3規則の候補と公式根拠を本文なしのJSONで返します。BR/Client Scriptの規則を評価するときは`selection_mode=review_targets`を明示し、0.3 JSONの制限・取得範囲を確認してください。[PDI対象選択E2Eは5成功・0スキップ](docs/E2E_BEST_PRACTICE_TARGET_SELECTION_2026-10-18.md)：既存BR10件への解析到達と省略時の0.2互換性を確認しました。[非アクティブ合成Client ScriptのE2E](docs/E2E_BEST_PRACTICE_CLIENT_FIXTURE_2026-10-18.md)でもAU-CL-004の候補1件を確認しました。件数・受信量・全体60秒の上限は不変です。UI実行、人による規則承認・独立品質評価は未確認で、「安全」「違反確定」を意味しません。詳細は[利用例・制限](docs/BEST_PRACTICE_BP5_MCP_REGISTRATION.md)。
### v1.13 ハイライト
- **Node.js 22.12 以上が必要です**（v1.12.0〜）。Node 20 は 2026 年 4 月に EOL を迎えました。MCP クライアント設定の `command` が Node 22.12 以上を起動することを確認してください
- Excel 取り込み（`import_excel_to_import_set`）を、外部ライブラリを使わない読み取り専用パーサに置き換え。インストール時の依存が 231 → 137 パッケージ・65 MB → 31 MB になり、`npm audit` は 0 件
- Excel 取り込みの改善: 空行より後の行も取り込む（従来は欠落）、ヘッダー行の数式は拒否、和暦など日本語の組み込み日付書式を日付として取り込む
- stdio で起動したとき、`.env` の読み込みメッセージが stdout に混ざってプロトコルを壊す問題を修正（v1.11.8）
### v1.11.7 ハイライト
- `list_active_events` は未処理イベント（`Ready` / `Error`）を新しい順に取得するよう改善。処理済みを含む全状態を検索する場合は `state: "all"` を指定
- Smart Query・USEM・Now Assist メタデータ・ServiceNow Store の読み取り専用 E2E を追加。2026-09-26 の追加分は **21 件成功・4 件スキップ**（対象データ不足）。AI 起動やレコード更新は実施していません
- 詳細は [CHANGELOG](CHANGELOG.md) と [E2E 検証記録](docs/E2E_READ_COVERAGE_2026-09-26.md) を参照
### v1.11.6 までの主な変更
- Update Set 内のスクリプト系 Customer Update から、固定バージョンの npm コンポーネントを検出し、OSV の advisory と照合する読み取り専用 SCA ツール `scan_update_set_sca` を追加
- SCA は本文・payload・一致箇所を返さず、メタデータ・ハッシュ・PURL・証跡のみを返却。未解決参照や照会失敗を「脆弱性なし」と誤認しない JSON 契約を提供
- Event Management のアラート一覧・詳細・集計・確認・クローズ・更新の 6 ツールを追加（`itom_engineer` パッケージ）
- SOAP、Security Incident Response、脆弱性スキャン、バックグラウンドスクリプト実行、Agile Epic の実機で判明した不整合を修正
- v1.11.6 で ExcelJS 配下の `uuid` を固定しましたが、npm の `overrides` はインストール先には適用されないため、利用者環境の `npm audit` 警告は v1.13.0 で ExcelJS を依存から外すまで残っていました
---
## このツールが何をするか（初心者向け）
```mermaid
flowchart TD
subgraph PC["💻 あなたの PC"]
direction TB
AI["🤖 AI クライアント
(Claude Desktop / Cursor / VS Code)"]
MCP["⚙️ servicenow-mcp サーバー
(ここがこのツール)"]
AI <-->|"MCP プロトコル (stdio)"| MCP
end
SN["☁️ ServiceNow インスタンス
(開発 PDI または 社内環境)"]
MCP <-->|"HTTPS / REST API
(インターネット経由)"| SN
style PC fill:#f0f7ff,stroke:#00509E,stroke-width:2px,color:#333,stroke-dasharray: 5 5
style AI fill:#ffffff,stroke:#333,stroke-width:2px,color:#000
style MCP fill:#e6ffe6,stroke:#008000,stroke-width:2px,color:#000
style SN fill:#fff0f0,stroke:#cc0000,stroke-width:2px,color:#000
```
**ポイント:**
- サーバーは **あなたの PC 上で動く** Node.js プロセスです。通常のツールは ServiceNow とだけ通信します。SCA の OSV 脆弱性照会など、外部連携を行うツールは個別に明示します
- AI クライアントと stdio（標準入出力）で通信するため、ポート開放やネットワーク設定は不要
- ServiceNow へは HTTPS で接続します。既存のブラウザアクセスと同じ経路です
---
## 推奨環境
> **まずは開発インスタンス (PDI) でお試しください。**
> 本番環境への接続は技術的には可能ですが、AI の誤操作・意図しないレコード更新を防ぐため、
> **はじめは読み取り専用モード (`WRITE_ENABLED=false`) で動作を確認してから本番適用してください。**
| 環境 | 推奨度 | 注意 |
|------|--------|------|
| **PDI (無料開発インスタンス)** | ★★★ 推奨 | 無料。操作の影響なし。初めて使う方はここから |
| **社内開発・検証インスタンス** | ★★☆ 可 | チームと共有している場合は読み取り専用で開始 |
| **本番インスタンス** | ★☆☆ 要注意 | `WRITE_ENABLED=false` + 専用サービスアカウント必須 |
無料 PDI → [developer.servicenow.com](https://developer.servicenow.com)
---
## 動作の仕組み
```mermaid
sequenceDiagram
participant U as あなた
participant AI as AI クライアント
(Claude / Cursor)
participant MCP as servicenow-mcp
(ローカル PC)
participant SN as ServiceNow
(クラウド)
U->>AI: 「P1 インシデントを一覧表示して」
AI->>MCP: list_incidents(priority=1) を呼び出す
MCP->>MCP: 権限チェック (読み取りは常に許可)
MCP->>SN: GET /api/now/table/incident?sysparm_query=priority=1
SN-->>MCP: JSON でインシデント一覧を返す
MCP-->>AI: ツール結果を返す
AI-->>U: 「現在 3 件の P1 インシデントがあります...」
```
---
## はじめての方向け — 5 分セットアップ
```mermaid
flowchart TD
A([はじめる]) --> B{ServiceNow\nインスタンスはある?}
B -->|ない| C[developer.servicenow.com\nで無料 PDI を取得\n約 10 分]
B -->|ある| D
C --> D{Node.js 22.12+\nインストール済み?}
D -->|ない| E[nodejs.org から\nLTS 版をインストール]
E --> F
D -->|あり| F[ターミナルでコマンド実行]
F --> G["npm install -g @tedorigawa001/servicenow-mcp"]
G --> H["servicenow-mcp setup"]
H --> I{セットアップ\nウィザード}
I --> J[インスタンス URL を入力\n例: https://dev12345.service-now.com]
J --> K[OAuth グラントタイプを選択\nclient_credentials または password]
K --> L[OAuth 認証情報を入力]
L --> M[接続テスト]
M -->|失敗| N[URL・認証情報を確認]
N --> L
M -->|成功| O[AI クライアントを自動検出]
O --> P[設定ファイルを自動書き込み]
P --> Q([完了！\nAI から ServiceNow に繋がります])
```
### ステップ 1 — インストール
**方法 A: npm からインストール（推奨・最速）**
```bash
# Node.js のバージョン確認 (22.12 以上が必要)
node --version
# グローバルインストール
npm install -g @tedorigawa001/servicenow-mcp
# セットアップウィザードを起動
servicenow-mcp setup
```
**方法 B: ソースからビルド（開発・カスタマイズしたい方向け）**
```bash
# リポジトリをクローン
git clone https://github.com/tedorigawa001/ServiceNow-MCP.git
cd ServiceNow-MCP
# 依存パッケージのインストール & コンパイル
npm install
npm run build
# セットアップウィザードを起動
npm run setup
```
どちらの方法でも、ウィザードが Claude Desktop・Cursor・VS Code などを自動検出し、設定ファイルを自動で書き込みます(VS Code は `npx ... server` 起動 + シークレットは `inputs` 化、それ以外は `dist/server.js` の絶対パス)。
### ステップ 2 — AI クライアントを再起動
設定ファイルを書き込んだあと、Claude Desktop や Cursor を **一度完全に終了して再起動** してください。
### ステップ 3 — 動作確認
AI に話しかけてみましょう:
```
「ServiceNow に接続して、直近のインシデントを 5 件表示してください」
```
---
## Docker での起動
### ソースビルド vs Docker — どちらを選ぶか
| 比較項目 | ソースビルド（`node dist/server.js`） | Docker（`docker run`） |
|---------|--------------------------------------|----------------------|
| **起動速度** | ✅ 即時 | ⚠️ コンテナ起動分のオーバーヘッドあり |
| **設定のシンプルさ** | ⚠️ 絶対パスが必要 | ✅ `docker` コマンドのみ |
| **環境依存** | Node.js 22.12+ が必要 | Docker が必要 |
| **環境の統一** | ⚠️ ホスト環境に依存 | ✅ どの PC でも同一環境 |
| **チーム配布・CI/CD** | ⚠️ 各自でビルドが必要 | ✅ イメージを共有するだけ |
| **推奨シーン** | 個人利用・開発 | チーム配布・本番運用 |
### イメージのビルドと起動
```bash
# イメージをビルド
docker build -t servicenow-mcp .
# 起動
docker run --rm -i \
-e SERVICENOW_INSTANCE_URL=https://yourinstance.service-now.com \
-e SERVICENOW_OAUTH_CLIENT_ID=your_client_id \
-e SERVICENOW_OAUTH_CLIENT_SECRET=your_client_secret \
servicenow-mcp
```
Password Grant を使う場合は、さらに以下を追加します:
```bash
-e SERVICENOW_OAUTH_USERNAME=service_account_user \
-e SERVICENOW_OAUTH_PASSWORD=service_account_password \
```
### AI クライアントから接続する（Claude Desktop）
`claude_desktop_config.json` の `command` / `args` を以下のように変更します。
Client Credentials を使う場合は `SERVICENOW_OAUTH_USERNAME` と `SERVICENOW_OAUTH_PASSWORD` の 2 行を省略してください。
```json
{
"mcpServers": {
"servicenow": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"-e", "SERVICENOW_INSTANCE_URL=https://yourinstance.service-now.com",
"-e", "SERVICENOW_OAUTH_CLIENT_ID=your_client_id",
"-e", "SERVICENOW_OAUTH_CLIENT_SECRET=your_client_secret",
"-e", "SERVICENOW_OAUTH_USERNAME=service_account_user",
"-e", "SERVICENOW_OAUTH_PASSWORD=service_account_password",
"servicenow-mcp"
]
}
}
}
```
> **注意**: `-i` フラグは必須です。MCP は stdio（標準入出力）で通信するため、インタラクティブモードが必要です。
> **HTTP モードで起動する場合**: コンテナ内の既定バインドは `127.0.0.1` のため公開ポートからは到達できません。
> `-e MCP_TRANSPORT=http -e MCP_HTTP_HOST=0.0.0.0 -p 3000:3000` を付与してください。
> イメージは非 root(`node` ユーザー)で動作し、`EXPOSE 3000` 済みです。
---
## 認証方式（OAuth 2.0 のみ）
このサーバーは **OAuth 2.0 のみ** をサポートします。Basic Auth はセキュリティリスク（資格情報が平文で設定ファイルに残る）があるため廃止しました。
OAuth 2.0 には 2 種類のグラントタイプがあり、用途に応じて自動選択されます。
```mermaid
flowchart TD
START([OAuth 設定]) --> Q1{ユーザー名/パスワードを\n設定する?}
Q1 -->|しない| CC["Client Credentials Grant\ngrant_type=client_credentials\n\nclient_id + client_secret のみ\n推奨: サービス間連携・自動化"]
Q1 -->|する| PW["Password Grant\ngrant_type=password\n\nclient_id + client_secret\n+ username + password\n既存ユーザー権限を引き継ぎたい場合"]
CC --> CC_NOTE["ServiceNow が Application Registry 上の\nスコープで API を実行する"]
PW --> PW_NOTE["指定ユーザーの権限でAPIを実行する\n(ACL・ロールがそのまま適用)"]
```
### Client Credentials（推奨）
`client_id` と `client_secret` だけで動作します。ユーザー資格情報が不要なため、サービス間連携に最適です。
```bash
SERVICENOW_INSTANCE_URL=https://dev12345.service-now.com
SERVICENOW_OAUTH_CLIENT_ID=your_client_id
SERVICENOW_OAUTH_CLIENT_SECRET=your_client_secret
```
### Password Grant（ユーザー権限を引き継ぐ場合）
特定ユーザーの ACL・ロールで API を実行したい場合に使います。
```bash
SERVICENOW_INSTANCE_URL=https://dev12345.service-now.com
SERVICENOW_OAUTH_CLIENT_ID=your_client_id
SERVICENOW_OAUTH_CLIENT_SECRET=your_client_secret
SERVICENOW_OAUTH_USERNAME=svc_mcp
SERVICENOW_OAUTH_PASSWORD=your_password
```
---
## OAuth セットアップ手順
> OAuth は ServiceNow の管理者権限が必要です。PDI では自分で設定できます。
### ServiceNow 側の設定
**Step 1 — OAuth アプリケーションレジストリを作成**
1. ServiceNow にログイン
2. 左メニューで「Application Registry」を検索
3. 「New」→ **「New Inbound Integration Experience」** を選択
> ⚠️ 「[Deprecated UI] Create an OAuth API endpoint for external clients」は**旧 UI** です。
> 現行バージョンでは **New Inbound Integration Experience** を使用してください。
グラントタイプによって設定が異なります。
#### Client Credentials Grant（推奨）
> **重要**: Client Credentials Grant では ServiceNow 側でユーザーを指定する必要があります。
> これは標準 OAuth の仕様とは異なる ServiceNow 固有の要件です。
> アクセストークンは「どのユーザーとして API を実行するか」を ServiceNow が決定するために使用します。
```
Name: servicenow-mcp
Token Format: JWT ← 必須
Client ID: (自動生成)
Client Secret: (自動生成 → コピーして保存)
Redirect URL: http://localhost
Access Token Lifespan: 1800 (秒)
Default Grant user: svc_mcp ← 必須: API を実行するサービスアカウントを指定
```
`Default Grant user` に指定したユーザーの **ロール・ACL** が API 実行時に適用されます。
このユーザーには必要最小限の ServiceNow ロール（例: `itil`, `admin` 等）を付与してください。
#### Password Grant
```
Name: servicenow-mcp
Token Format: JWT ← 必須
Client ID: (自動生成)
Client Secret: (自動生成 → コピーして保存)
Redirect URL: http://localhost
Access Token Lifespan: 1800 (秒)
Default Grant user: (不要 — username/password で指定したユーザーが使われます)
```
「Submit」で保存。
**Step 2 — 生成された Client ID / Secret を確認**
作成したレジストリを開き、`Client ID` と `Client Secret` をメモします。
```mermaid
flowchart LR
A[Application Registry を開く] --> B[Client ID をコピー]
A --> C[Client Secret をコピー\nShow をクリック]
B & C --> D[環境変数に設定]
```
### MCP サーバー側の設定
#### Client Credentials Grant
```bash
SERVICENOW_INSTANCE_URL=https://dev12345.service-now.com
SERVICENOW_OAUTH_CLIENT_ID=your_client_id
SERVICENOW_OAUTH_CLIENT_SECRET=your_client_secret
# SERVICENOW_OAUTH_USERNAME / PASSWORD は不要
```
#### Password Grant
```bash
SERVICENOW_INSTANCE_URL=https://dev12345.service-now.com
SERVICENOW_OAUTH_CLIENT_ID=your_client_id
SERVICENOW_OAUTH_CLIENT_SECRET=your_client_secret
SERVICENOW_OAUTH_USERNAME=svc_mcp
SERVICENOW_OAUTH_PASSWORD=your_password
```
接続確認:
```bash
node dist/cli/index.js auth test
```
---
## AI クライアント別セットアップ
### Claude Desktop
設定ファイル: `~/Library/Application Support/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"servicenow": {
"command": "node",
"args": ["/path/to/servicenow-mcp/dist/server.js"],
"env": {
"SERVICENOW_INSTANCE_URL": "https://dev12345.service-now.com",
"SERVICENOW_OAUTH_CLIENT_ID": "your_client_id",
"SERVICENOW_OAUTH_CLIENT_SECRET": "your_client_secret",
"WRITE_ENABLED": "false"
}
}
}
}
```
> `WRITE_ENABLED: "false"` にしておくと読み取り専用になります。動作確認が終わったら `"true"` に変更できます。
> ユーザー権限を引き継ぐ場合は `SERVICENOW_OAUTH_USERNAME` と `SERVICENOW_OAUTH_PASSWORD` も追加してください。
### Claude Code CLI
```bash
claude mcp add servicenow node /path/to/servicenow-mcp/dist/server.js \
--env SERVICENOW_INSTANCE_URL=https://dev12345.service-now.com \
--env SERVICENOW_OAUTH_CLIENT_ID=your_client_id \
--env SERVICENOW_OAUTH_CLIENT_SECRET=your_client_secret \
--env WRITE_ENABLED=false
```
### Cursor
設定ファイル: `.cursor/mcp.json`
```json
{
"mcpServers": {
"servicenow": {
"command": "node",
"args": ["/path/to/servicenow-mcp/dist/server.js"],
"env": {
"SERVICENOW_INSTANCE_URL": "https://dev12345.service-now.com",
"SERVICENOW_OAUTH_CLIENT_ID": "your_client_id",
"SERVICENOW_OAUTH_CLIENT_SECRET": "your_client_secret",
"WRITE_ENABLED": "true",
"SCRIPTING_ENABLED": "true"
}
}
}
}
```
### VS Code (1.99+)
設定ファイル: `.vscode/mcp.json`(ワークスペースルート)
`.vscode/` はコミットされがちなので、シークレットは平文で書かず VS Code の `inputs`(初回起動時にプロンプト表示・暗号化保存)に逃がします。セットアップウィザードもこの形式で書き込みます。
```json
{
"inputs": [
{
"type": "promptString",
"id": "servicenow-client-secret",
"description": "ServiceNow OAuth client secret",
"password": true
}
],
"servers": {
"servicenow-mcp": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@tedorigawa001/servicenow-mcp", "server"],
"env": {
"SERVICENOW_INSTANCE_URL": "https://dev12345.service-now.com",
"SERVICENOW_OAUTH_CLIENT_ID": "your_client_id",
"SERVICENOW_OAUTH_CLIENT_SECRET": "${input:servicenow-client-secret}"
}
}
}
}
```
### 対応クライアント一覧
| クライアント | 種別 | ガイド |
|------------|------|--------|
| Claude Desktop | デスクトップ | [Setup](clients/claude-desktop/SETUP.md) |
| Claude Code CLI | ターミナル | [Setup](clients/claude-code/SETUP.md) |
| Cursor | AI エディタ | [Setup](clients/cursor/SETUP.md) |
| Windsurf | AI エディタ | [Setup](docs/CLIENT_SETUP.md) |
| VS Code (Native MCP 1.99+) | IDE | [Setup](clients/vscode/SETUP.md) |
| VS Code + GitHub Copilot | IDE | [Setup](clients/vscode/SETUP.md) |
| VS Code + Continue.dev | IDE | [Setup](docs/CLIENT_SETUP.md) |
| VS Code + Cline | IDE | [Setup](docs/CLIENT_SETUP.md) |
| JetBrains AI | IDE | [Setup](docs/CLIENT_SETUP.md) |
| Amazon Q Developer | IDE / CLI | [Setup](docs/CLIENT_SETUP.md) |
| ChatGPT / OpenAI API | API | [Setup](clients/codex/SETUP.md) |
| Google Gemini API | API | [Setup](clients/gemini/SETUP.md) |
| Ollama (ローカル LLM) | ローカル | [Setup](docs/CLIENT_SETUP.md) |
全クライアントのセットアップ詳細 → [docs/CLIENT_SETUP.md](docs/CLIENT_SETUP.md)
---
## トランスポート（stdio / HTTP）
デフォルトは **stdio**（標準入出力）で、ポート開放やネットワーク設定は不要です。
ブラウザ経由の接続（Claude.ai Web UI）、Docker コンテナ公開、複数クライアントでのサーバー共有、
CI/CD からの呼び出しが必要な場合は **Streamable HTTP** トランスポートに切り替えられます。
```bash
# HTTP トランスポートで起動（トークンはランダムな十分長い値を使用）
MCP_TRANSPORT=http MCP_HTTP_AUTH_TOKEN=replace-with-a-random-secret node dist/server.js
# → http://127.0.0.1:3000/mcp で待ち受け、GET /health でヘルスチェック
```
| 環境変数 | デフォルト | 説明 |
|---|---|---|
| `MCP_TRANSPORT` | `stdio` | `http` で Streamable HTTP に切り替え |
| `MCP_HTTP_PORT` | `3000` | 待ち受けポート |
| `MCP_HTTP_HOST` | `127.0.0.1` | バインドアドレス（外部公開時は `0.0.0.0`）|
| `MCP_HTTP_PATH` | `/mcp` | MCP エンドポイントのパス |
| `MCP_HTTP_AUTH_TOKEN` | (必須) | MCP エンドポイント用 Bearer トークン。未設定時は `/mcp` への要求をすべて401で拒否 |
| `MCP_HTTP_CORS_ORIGIN` | `*` | CORS 許可オリジン |
| `MCP_HTTP_ALLOWED_HOSTS` | (なし) | カンマ区切り。指定すると DNS リバインディング保護を有効化 |
| `MCP_HTTP_ALLOWED_ORIGINS` | (なし) | カンマ区切り。Origin ヘッダの許可リスト |
| `MCP_HTTP_MAX_BODY_BYTES` | `1048576` | JSON-RPC 要求本文の最大バイト数 |
| `MCP_HTTP_MAX_SESSIONS` | `100` | 同時 HTTP MCP セッションの上限 |
| `MCP_HTTP_SESSION_IDLE_TIMEOUT_MS` | `1800000` | 未使用セッションを閉じるまでのミリ秒 |
セッションは MCP 仕様に従い、`initialize` 応答の `Mcp-Session-Id` ヘッダで払い出され、
以降のリクエストで再利用します（`DELETE /mcp` でセッション終了）。HTTP 接続するクライアント設定例:
```json
{
"mcpServers": {
"servicenow": {
"url": "http://localhost:3000/mcp",
"headers": { "Authorization": "Bearer replace-with-a-random-secret" }
}
}
}
```
> **セキュリティ注意**: HTTP MCP は `MCP_HTTP_AUTH_TOKEN` を必須とします。デフォルトは loopback（`127.0.0.1`）バインドです。`MCP_HTTP_HOST=0.0.0.0`
> で外部公開する場合は、リバースプロキシでの TLS 終端・認証、および `MCP_HTTP_ALLOWED_HOSTS` /
> `MCP_HTTP_ALLOWED_ORIGINS` による保護を推奨します。
---
## 権限設定（何ができるかを制御する）
デフォルトは**読み取り専用**です。操作範囲を広げたい場合は環境変数で段階的に有効化します。
```mermaid
graph TD
T0["🛡️ Tier 0: 常時有効 (デフォルト)
インシデント表示 / KB 検索 / レコード参照..."]
T1["✏️ Tier 1: WRITE_ENABLED=true
インシデント作成・更新 / 変更リクエスト管理..."]
T2["🧩 Tier 2: CMDB_WRITE_ENABLED=true (Tier 1も必要)
CI の作成・更新 / 関連付け管理..."]
T3["⚙️ Tier 3: SCRIPTING_ENABLED=true (Tier 1も必要)
ビジネスルール / スクリプト / Update Set..."]
TAI["🤖 Tier AI: NOW_ASSIST_ENABLED=true
NLQ / AI サマリー / Agentic Playbook..."]
T0 --> T1
T1 --> T2
T1 --> T3
T0 -.->|"独立オプション"| TAI
style T0 fill:#f5f5f5,stroke:#999,stroke-width:2px,color:#333
style T1 fill:#e3f2fd,stroke:#2196f3,stroke-width:2px,color:#000
style T2 fill:#fff3e0,stroke:#ff9800,stroke-width:2px,color:#000
style T3 fill:#ffebee,stroke:#f44336,stroke-width:2px,color:#000
style TAI fill:#f3e5f5,stroke:#9c27b0,stroke-width:2px,color:#000
```
**本番環境で使う場合の推奨設定:**
```bash
WRITE_ENABLED=false # まずは読み取りのみで確認
CMDB_WRITE_ENABLED=false
SCRIPTING_ENABLED=false # 本番では原則 false のまま
```
---
## ロールベース ツールパッケージ
`MCP_TOOL_PACKAGE` 環境変数でツールを絞り込めます。全部入りではなく、用途に応じたセットを使うと AI が迷わずに済みます。
```mermaid
mindmap
root((ツールパッケージ))
full
全503ツール
service_desk
インシデント管理
タスク/承認
KB検索
SLA確認
change_coordinator
変更管理
CABスケジュール
CMDB参照
platform_developer
スクリプト管理
ACL/UI Policy
ATFテスト
Update Set
system_administrator
ユーザー/グループ管理
レポート/ログ
PA ダッシュボード
itom_engineer
CMDB
Discovery
MIDサーバー
ai_developer
Now Assist
NLQ
Agentic Playbooks
secops_analyst
VI作成/RT横断検索
グルーピング診断
SLA/例外承認
```
| パッケージ名 | 対象ロール | 主なツール |
|------------|----------|-----------|
| `full` | 管理者 | 全ツール (503) |
| `service_desk` | L1/L2 エージェント | インシデント・タスク・KB・SLA |
| `change_coordinator` | 変更管理者 | 変更リクエスト・CAB・CMDB |
| `knowledge_author` | KB 著者 | KB 作成・公開 |
| `catalog_builder` | カタログ管理者 | カタログ・承認ルール |
| `system_administrator` | システム管理者 | ユーザー・グループ・レポート |
| `platform_developer` | 開発者 | スクリプト・ATF・Update Set |
| `portal_developer` | ポータル開発者 | ポータル・ウィジェット・UX |
| `integration_engineer` | 統合エンジニア | REST・Transform・イベント |
| `itom_engineer` | ITOM エンジニア | CMDB・Discovery(実行履歴/エラー調査)・MID ヘルス・ACC・Event Management アラート管理 |
| `agile_manager` | スクラムマスター | ストーリー・エピック |
| `ai_developer` | AI 開発者 | Now Assist・NLQ・Playbook |
| `itam_analyst` | 資産管理者 | 資産・ライセンス・契約・SAM Pro(ソフトウェア資産管理) |
| `secops_analyst` | SecOps アナリスト | 脆弱性(VI/RT)・RT横断検索・グルーピング診断・USEM・SLA・例外承認 |
| `devops_engineer` | DevOps | パイプライン・デプロイ |
詳細 → [docs/TOOL_PACKAGES.md](docs/TOOL_PACKAGES.md)
---
## 使用例
### 自然言語で操作する
```
「Network Operations グループの P1 インシデントをすべて表示して」
「INC0012345 に "調査中。30 分以内に更新します" とワークノートを追加して」
「SAP 本番システムの障害でインシデントを作成して。
優先度 Critical、Network Ops グループに割り当てて」
「先月の Priority 別インシデント件数をグラフ用データで出して」
```
### 典型的なやりとりの流れ
```mermaid
sequenceDiagram
participant U as あなた
participant AI as AI アシスタント
participant MCP as servicenow-mcp
participant SN as ServiceNow
U->>AI: 「SAP の P1 インシデントを作って」
AI->>MCP: create_incident を呼び出す
MCP->>MCP: WRITE_ENABLED チェック ✅
MCP->>SN: POST /api/now/table/incident
SN-->>MCP: INC0099001 作成完了
MCP-->>AI: 作成結果を返す
AI-->>U: 「INC0099001 を作成しました」
U->>AI: 「SAP サーバーの CMDB 依存関係も確認して」
AI->>MCP: search_cmdb_ci + list_relationships
MCP->>SN: CMDB API を 2 回呼び出す
SN-->>MCP: 依存 CI 8 件
MCP-->>AI: 依存関係リスト
AI-->>U: 「SAP-PROD-DB01 は 8 つの CI に依存しています」
```
### Update Set の第三者コンポーネントを SCA する
`scan_update_set_sca` は **読み取り専用**で Update Set 内のスクリプト系 Customer Update を収集し、固定バージョンが確認できる npm コンポーネントを検出します。既定では [OSV](https://osv.dev) に照会して advisory を JSON で返します。コード本文・payload・一致箇所の文字列は返しません。
```
「Release 1.12 Update Set を SCA スキャンして。検出したコンポーネント、
脆弱性、照会できなかった項目、次の対応を JSON の根拠だけで報告して」
```
ローカル収集だけを先に確認したい場合は、AI に `lookup_vulnerabilities: false` を指定します。
```json
{
"update_set": "46f0...",
"max_records": 50,
"lookup_vulnerabilities": false
}
```
AI への報告依頼例:
```
scan_update_set_sca の JSON だけを根拠に報告してください。
critical / high を最優先にし、各 finding は component、installed_version、
advisory_id、fixed_versions、evidence の asset_type と asset_name を示してください。
summary.assessment、lookup.status、errors、unresolved_references、truncated を必ず確認し、
対象外・未照会・失敗を「脆弱性なし」と表現しないでください。
修正は自動実行せず、Update Set の変更案と確認手順を提案してください。
```
> **制約**: `findings` が空でも安全性は証明されません。バージョン範囲、`latest` のような CDN alias、バージョンなしのモジュール参照は CVE 照合できず `unresolved_references` として返ります。CDN URL を検出しても、そのライブラリが実際にロード・実行されたことまでは示しません。また SCA は依存コンポーネントを対象にするものであり、ServiceNow のカスタムスクリプトに対する SAST、権限設計、クエリ安全性のレビューを代替しません。
### スラッシュコマンド & @メンション
```
/morning-standup → P1/P2 オープンインシデント・当日変更・SLA 違反のサマリー
/my-tickets → 自分に割り当てられたオープンタスク一覧
/p1-alerts → アクティブな P1 インシデント一覧
@my-incidents → 自分のインシデントをコンテキストに追加
@ci:web-prod-01 → CMDB CI レコードをコンテキストに追加
@kb:VPN-setup → KB 記事をコンテキストに追加
```
120+ の実例 → [EXAMPLES.md](EXAMPLES.md)
---
## マルチインスタンス対応
```mermaid
graph LR
User["あなたの PC\n(AI + MCP サーバー)"] -->|dev| DEV[(開発 PDI\ndev12345.service-now.com)]
User -->|staging| STG[(検証\nstg.company.com)]
User -->|prod| PRD[(本番\nacme.service-now.com)]
```
```json
{
"default_instance": "dev",
"instances": {
"dev": {
"url": "https://dev12345.service-now.com",
"client_id": "dev-client-id",
"client_secret": "dev-client-secret"
},
"prod": {
"url": "https://acme.service-now.com",
"auth": "oauth",
"client_id": "xxx",
"client_secret": "yyy",
"username": "svc_account",
"password": "zzz"
}
}
}
```
```bash
SN_INSTANCES_CONFIG=/path/to/instances.json
```
詳細 → [docs/MULTI_INSTANCE.md](docs/MULTI_INSTANCE.md)
---
## モジュールカバレッジ
```mermaid
graph TB
subgraph ITSM["ITSM & サービス管理"]
I1[インシデント管理]
I2[問題管理]
I3[変更管理]
I4[タスク管理]
I5[ナレッジベース]
I6[サービスカタログ]
end
subgraph PLATFORM["プラットフォーム & 開発"]
P1[スクリプト/ビジネスルール]
P2[Flow Designer]
P3[Service Portal / UIB]
P4[ATF テスト]
P5[Update Set 管理]
P6[App Studio]
end
subgraph OPS["運用 & 分析"]
O1[CMDB / ITOM]
O2[Performance Analytics]
O3[レポート / 集計]
O4[通知 / 添付]
O5[システムプロパティ]
O6[DevOps パイプライン]
O7[インスタンス診断 / 性能履歴]
end
subgraph EXTENDED["拡張モジュール"]
E1[HRSD]
E2[CSM]
E3[SecOps / GRC]
E4[Agile / Scrum]
E5[IT 資産管理]
E6[Virtual Agent]
end
subgraph AI["AI & インテグレーション"]
A1[Now Assist / AI]
A2[Integration Hub]
A3[Machine Learning]
A4[モバイル]
A5[ワークスペース]
end
```
---
## プロジェクト構造
```
servicenow-mcp/
├── src/
│ ├── server.ts # MCP サーバーエントリーポイント
│ ├── servicenow/
│ │ ├── client.ts # REST API クライアント (OAuth)
│ │ ├── instances.ts # マルチインスタンスマネージャー
│ │ └── types.ts # TypeScript 型定義
│ ├── tools/ # 47 ドメインモジュール (503 ツール)
│ │ ├── index.ts # ツールルーター & パッケージ定義
│ │ ├── incident.ts
│ │ ├── change.ts
│ │ ├── knowledge.ts
│ │ └── ...
│ ├── prompts/ # スラッシュコマンド定義
│ ├── resources/ # @メンション定義
│ ├── cli/ # セットアップウィザード
│ └── utils/
│ ├── permissions.ts # 5 段階権限ゲート
│ └── errors.ts
├── tests/ # 通常テスト・実機 E2E (Vitest)
├── docs/ # ドキュメント
└── instances.example.json
```
---
## 開発
```bash
npm install # 依存パッケージのインストール
npm run build # TypeScript → dist/ にコンパイル
npm test # 通常テストを実行（実機 E2E は別途 opt-in）
npm run dev # ウォッチモード
npm run type-check # 型チェックのみ
npm run lint # ESLint
```
### 実機 E2E の検証範囲
追加の読み取り専用 E2E（2026-09-26）は、4 スイート・25 ケース中 **21 件成功、4 件スキップ**です。
スキップは VI／RT／グループの対象レコード不足による詳細取得テストで、成功件数には含めていません。
Now Assist はメタデータ取得のみで、AI 推論・生成・プレイブック起動は未検証です。
MCP登録時点のE2Eコード静的集計記録は **241／503 ツール（約47.9%）**です（今回追加した試験を含む全体対象数の再集計ではありません）。
ベストプラクティスレビューは今回、実機の取得/集約2件成功・payload解析1件スキップで、詳細は[検証記録](docs/E2E_BEST_PRACTICE_REVIEW_2026-10-18.md)を参照してください。
これはコード行・分岐のカバレッジや、全241ツールの実機成功率を示す数値ではありません。
テスト件数は変更されるため、通常テストの最新件数は `npm test` の実行結果を参照してください。
PDI と OAuth を設定したうえで、今回の読み取り専用スイートだけを実行する例:
```bash
RUN_E2E=true WRITE_ENABLED=false SCRIPTING_ENABLED=false \
npx vitest run -c vitest.e2e.config.ts \
tests/e2e/smart-query.e2e.test.ts \
tests/e2e/usem-read.e2e.test.ts \
tests/e2e/now-assist-read.e2e.test.ts \
tests/e2e/store-read.e2e.test.ts
```
Now Assist メタデータのテストは `NOW_ASSIST_ENABLED=true` の場合のみ実行します。
不足するプラグイン・テストデータは理由付きでスキップし、API／ACL エラーは失敗として扱います。
詳細は [E2E 検証記録](docs/E2E_READ_COVERAGE_2026-09-26.md) と [CONTRIBUTING.md](CONTRIBUTING.md) を参照してください。
---
## よくある質問
**ServiceNow の API 知識は必要ですか？**
いいえ。「P1 インシデントを一覧表示して」のように日本語で話しかけるだけです。API 呼び出しはサーバーが自動で行います。
**本番環境に接続しても大丈夫ですか？**
`WRITE_ENABLED=false`（デフォルト）で接続する分には読み取りのみで安全です。書き込みを有効にする前に、必ず開発環境で動作を確認してください。
**無料で使えますか？**
このサーバー自体は MIT ライセンスで無料です。ServiceNow の無料 PDI（Personal Developer Instance）も [developer.servicenow.com](https://developer.servicenow.com) で取得できます。AI クライアント側（Claude Pro 等）の料金は各サービスに従います。
**MCP って何ですか？**
Model Context Protocol の略で、AI クライアントが外部ツールを呼び出すための標準規格です。Claude・Cursor などが対応しています。このサーバーは MCP に準拠しているため、対応 AI から自動的に発見・使用されます。
**複数インスタンスに接続できますか？**
はい。`instances.json` で dev / staging / prod を定義しておき、「本番インスタンスに切り替えて」と指示するだけで切り替わります。
---
## ドキュメント
| ガイド | 内容 |
|-------|------|
| [docs/INSTALLATION.md](docs/INSTALLATION.md) | 環境変数リファレンス |
| [docs/CLIENT_SETUP.md](docs/CLIENT_SETUP.md) | 全 AI クライアントのセットアップ |
| [docs/SERVICENOW_OAUTH_SETUP.md](docs/SERVICENOW_OAUTH_SETUP.md) | ServiceNow OAuth アプリ作成手順（詳細版） |
| [docs/TOOL_PACKAGES.md](docs/TOOL_PACKAGES.md) | ロールベースパッケージの詳細 |
| [docs/TOOLS.md](docs/TOOLS.md) | 全ツールのパラメータ・権限要件 |
| [docs/MULTI_INSTANCE.md](docs/MULTI_INSTANCE.md) | マルチインスタンス設定 |
| [docs/NOW_ASSIST.md](docs/NOW_ASSIST.md) | Now Assist / AI 統合 |
| [docs/ATF.md](docs/ATF.md) | ATF テストガイド |
| [EXAMPLES.md](EXAMPLES.md) | 120+ 実用例 |
| [SECURITY.md](SECURITY.md) | セキュリティポリシー・脆弱性報告 |
| [CHANGELOG.md](CHANGELOG.md) | 変更履歴 |
---
## コントリビュート
[CONTRIBUTING.md](CONTRIBUTING.md) をお読みの上、Pull Request をお送りください。
バグ報告・機能要望 → [Issue を開く](../../issues)
---
## セキュリティ
脆弱性を発見した場合は **公開 Issue には投稿せず**、[SECURITY.md](SECURITY.md) の責任ある開示プロセスに従ってください。
---
## ライセンス
[MIT](LICENSE) — 個人・商用利用とも無料。
---
**503 ツール · 47 モジュール · ローカル PC で動作 · 永久オープンソース**
役に立ったら ⭐ スターをお願いします — 他の人が見つけやすくなります。
[](https://github.com/tedorigawa001/ServiceNow-MCP/stargazers)