4
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

ServiceNow を AI から自然言語で操作する MCP サーバーを作ってみた

4
Posted at

ServiceNow を AI から自然言語で操作する MCP サーバーを作った

ServiceNow の操作を「インシデント作って」「P1 の一覧見せて」のような自然言語で完結させる MCP サーバーを OSS として公開しました。

GitHub: https://github.com/tedorigawa001/ServiceNow-MCP

なぜ作ったか

ServiceNow は非常に多機能なプラットフォームですが、日常的な操作(インシデント確認・ワークノート追加・変更リクエスト作成など)のたびにブラウザで何画面もクリックするのは手間です。

「AI に頼めば一発なのに」と思ったのが出発点です。MCP(Model Context Protocol)を使えば Claude や Cursor などの AI クライアントに ServiceNow のツールを持たせられます。

MCP とは

Model Context Protocol は、AI クライアントが外部ツール(API・DB・ファイルなど)を呼び出すための標準規格です。Claude・Cursor・VS Code Copilot などが対応しています。

MCP サーバーを実装すると、AI が「このツールを呼ぶべきだ」と判断したとき自動的に呼び出してくれます。開発者は「何をできるか」を JSON Schema で定義するだけです。

あなた:「P1 インシデントを一覧表示して」
    ↓
AI クライアント(Claude など)
    ↓ MCP プロトコル(stdio)
servicenow-mcp サーバー(ローカル PC)
    ↓ HTTPS / REST API
ServiceNow インスタンス(クラウド)

できること

対応モジュール(31 モジュール / 376 ツール)

カテゴリ 主な機能
ITSM インシデント・問題・変更・タスク管理
サービス管理 カタログ・KB・SLA・承認
プラットフォーム スクリプト・Flow Designer・ATF・Update Set
CMDB / ITOM CI 管理・Discovery・依存関係
拡張 HRSD・CSM・SecOps・Agile・資産管理
AI Now Assist・NLQ・Agentic Playbooks

使用例

image.png

スラッシュコマンド

MCP の Prompts 機能で、よく使う操作をスラッシュコマンドとして定義しています。

/morning-standup  → P1/P2 オープンインシデント・当日変更・SLA 違反のサマリー
/my-tickets       → 自分に割り当てられたオープンタスク一覧
/p1-alerts        → アクティブな P1 インシデント(最も古いもの順)

@メンション

@my-incidents     → 自分のインシデントをコンテキストに追加
@ci:web-prod-01   → CMDB CI レコードをコンテキストに追加
@kb:VPN-setup     → KB 記事をコンテキストに追加

セットアップ(5 分)

前提

  • Node.js 20.19+
  • ServiceNow インスタンス(無料 PDI でも OK)

PDI は developer.servicenow.com で無料取得できます。

1. クローンしてビルド

git clone https://github.com/tedorigawa001/ServiceNow-MCP.git
cd ServiceNow-MCP
npm install
npm run build
npm run setup   # ウィザード起動

ウィザードが ServiceNow インスタンス URL・OAuth 認証情報を聞いてきて、Claude Desktop / Cursor / VS Code の設定ファイルを自動で書き込みます。

2. ServiceNow 側の OAuth 設定

ServiceNow の System OAuth > Application Registry で OAuth アプリを作成します。

注意: 「New」をクリックしたとき必ず 「New Inbound Integration Experience」 を選択してください。「[Deprecated UI] Create an OAuth API endpoint for external clients」は旧 UI です。

設定値(Client Credentials Grant の場合):

Name:               servicenow-mcp
Token Format:       JWT          ← 必須
Redirect URL:       http://localhost
Access Token Lifespan: 1800
Default Grant user: svc_mcp     ← API を実行するサービスアカウント(必須)

Token Format は JWT が必須です。 デフォルトのまま作ると接続できません。

3. 環境変数の設定

SERVICENOW_INSTANCE_URL=https://dev12345.service-now.com
SERVICENOW_OAUTH_CLIENT_ID=your_client_id
SERVICENOW_OAUTH_CLIENT_SECRET=your_client_secret

4. Claude Desktop の設定例

~/Library/Application Support/Claude/claude_desktop_config.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"
      }
    }
  }
}

Claude Desktop を再起動すると、設定 > Developer > MCP Servers に servicenow が緑で表示されます。

5. 接続確認

node dist/cli/index.js auth test

Docker でも動く(オプション)

# ビルド
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
ソースビルド Docker
起動速度 ✅ 即時 ⚠️ 起動オーバーヘッドあり
設定 ⚠️ 絶対パスが必要 ✅ docker コマンドのみ
環境統一 ⚠️ ホスト依存 ✅ どの PC でも同一
推奨用途 個人・開発 チーム配布・本番

セキュリティ設計

OAuth 2.0 のみ(Basic Auth 廃止)

Basic Auth は設定ファイルに平文で残るため廃止し、OAuth 2.0 のみをサポートします。

グラントタイプは自動判定されます:

  • SERVICENOW_OAUTH_USERNAME / PASSWORD なし → client_credentials grant
  • あり → password grant

5 段階の権限ティア

デフォルトは 読み取り専用。操作範囲を環境変数で段階的に広げます。

Tier 0(デフォルト): 読み取りのみ
Tier 1: WRITE_ENABLED=true         → 作成・更新
Tier 2: CMDB_WRITE_ENABLED=true    → CMDB 書き込み
Tier 3: SCRIPTING_ENABLED=true     → スクリプト実行
Tier AI: NOW_ASSIST_ENABLED=true   → Now Assist

本番環境では WRITE_ENABLED=false から始めることを強く推奨します。

Encoded Query Injection 対策

ServiceNow の encoded query(priority=1^state!=6 のような形式)を組み立てる際、フィールド値をそのまま結合すると ^ を使ったクエリ注入が可能になります。

各フィールドに対して型別のバリデーションを実装しています:

  • sys_id: /^[0-9a-f]{32}$/i
  • REQ/RITM 番号: /^REQ\d{1,12}$/i
  • stage: 許可値の Set で検証
  • username: /^[a-zA-Z0-9._@\-]{1,100}$/

AI が機能を理解しやすくする工夫

MCP Annotations(2025-03 仕様)

376 ツール全てに annotations を付与し、AI クライアントが自動実行するか確認を求めるかを判断できるようにしています。

// 読み取り専用ツール → 確認不要
get_incident: { annotations: { readOnlyHint: true, idempotentHint: true } }

// 破壊的操作 → 確認を促す
close_incident: { annotations: { destructiveHint: true } }

// 冪等な書き込み
update_incident: { annotations: { idempotentHint: true } }

index.ts でツール名の prefix によって一括分類しています:

// get_*, list_*, search_* → readOnlyHint: true
// close_*, delete_*, resolve_*, cancel_* → destructiveHint: true
// update_*, set_*, approve_* → idempotentHint: true

Enum によるコード値の機械可読化

// 改善前: AI がテキストを解析して値を推測
urgency: { type: 'number', description: '1=High, 2=Medium, 3=Low' }

// 改善後: enum で機械可読
urgency: { type: 'integer', enum: [1, 2, 3], description: '1=High, 2=Medium, 3=Low' }

urgency・impact・priority・severity・state(Incident / Change / Request)など主要な coded field を共通定数ファイル schema-helpers.ts に集約し、全ツールから import しています。

ロールベースのツールパッケージ

400+ ツールを全部 AI に渡すと迷いが生じます。MCP_TOOL_PACKAGE 環境変数でロール別のサブセットを読み込めます。

MCP_TOOL_PACKAGE=service_desk       # ヘルプデスク向け
MCP_TOOL_PACKAGE=platform_developer # 開発者向け
MCP_TOOL_PACKAGE=change_coordinator # 変更管理者向け

まとめ

  • ServiceNow の操作を自然言語で完結できる
  • Claude・Cursor・VS Code など主要 AI クライアントに対応
  • OAuth 2.0 のみ、デフォルト読み取り専用で安全
  • Docker 対応でチーム配布も簡単
  • MCP annotations・enum でツールの AI 理解度を向上

まずは無料 PDI + Claude Desktop で試してみてください。

4
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
4
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?