servicenow-mcp

AIエージェントがTable APIを通じてServiceNowのインシデントを作成、検索、更新できる小さなMCPサーバーです。公式のPython mcp パッケージ（FastMCPスタイルのデコレータ）、httpx、python-dotenvを使用して構築されています。stdio上で動作します。

すべては単一のファイルに収められています: server.py。

Setup

Python 3.12以上とuvが必要です。

uv sync

server.pyの隣に.envファイルを作成し（git-ignoredされています）、インスタンスのベーシック認証情報を記述します。Personal Developer Instanceで十分です:

SNOW_INSTANCE_URL=https://devXXXXXX.service-now.com
SNOW_USERNAME=admin
SNOW_PASSWORD=your-password
# optional, default 15
SNOW_TIMEOUT_SECONDS=15

サーバーを実行します（stdin/stdout上でMCPを話すため、表示されるものはありません — MCPクライアントが起動する必要があります）:

uv run server.py

Registering with an MCP client

クライアントがプロジェクトディレクトリのuvを指すように設定し、.venvと.envが読み込まれるようにします:

{
  "mcpServers": {
    "servicenow": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/servicenow-mcp", "run", "server.py"]
    }
  }
}

Claude Codeの場合: claude mcp add servicenow -- uv --directory /absolute/path/to/servicenow-mcp run server.py。

クライアントの環境で既に設定されている環境変数は.envよりも優先されます。

Related MCP server: sn-mcp-bridge

Tools

すべてのツールはスタックトレースの代わりに可読性の高いツールエラーを発生させます（エージェントにはisErrorとして表示されます）。例:

• Authentication failed (401): check SNOW_USERNAME and SNOW_PASSWORD. ServiceNow said: User is not authenticated …

• Could not connect to https://…: [Errno 8] nodename nor servname provided … Check SNOW_INSTANCE_URL and your network connection.

• Timed out after 15s talking to https://… The instance may be hibernating (PDI) or unreachable.

• Incident 'INC9999999' was not found on https://….

• Forbidden (403): the user lacks permission … or the update was rejected by a business rule. ServiceNow said: … （例：解決フィールドなしでインシデントを解決しようとした場合）。

Design notes

• **ServiceNowClient**は単一のhttpx.AsyncClient（ベーシック認証、JSONヘッダー、タイムアウト）をラップし、create_record / query_records / get_record_by_number / update_recordを公開します。すべてのエラーは人間が読めるメッセージのServiceNowErrorに変換されます。

• ツールはget_client()を介してクライアントを取得します。テストではset_client(fake)を呼び出して、ネットワークに触れずにモックに差し替えることができます。

• レコードはsysparm_display_value=allで取得されるため、state/urgencyラベルはハードコードされたマップではなくインスタンス自体から取得されます（フレンドリーネームのエイリアスは入力専用です）。

• mcp 2.xではFastMCPがMCPServerに改名されました。server.pyは存在する方のモジュールをインポートするため、1.xと2.xの両方で動作します。

Smoke test

実際のインスタンスに対して実行します（1件のインシデントを作成）:

uv run python -c "
import asyncio, server
async def main():
    c = await server.create_incident('MCP server smoke test', 'created by smoke test')
    print(c)
    print(await server.query_incidents(query_text='MCP server smoke test'))
    print(await server.update_incident(c['number'], work_notes='hello from MCP'))
asyncio.run(main())
"