servicenow-mcp-agent
servicenow-mcp-agent
Claude エージェントに ServiceNow スタイルの ITSM ツールを公開する MCP サーバーと、エージェントがそれらを正しく使うかどうかを測定する評価ハーネスです。
注目すべき点は、エージェントが動作することではありません。このリポジトリは、24 の採点付きタスクに対して、ツール選択精度・タスク完了率・呼び出しあたりのレイテンシという 3 つの指標で、どの程度うまく動作するかを示していることです。
┌──────────────┐ Messages API ┌───────────────┐ MCP (stdio/HTTP) ┌──────────────────┐
│ Claude │◄─────tools────────│ ITSM agent │◄────tools/call───────│ MCP server │
│ (Sonnet 5) │─────tool_use─────►│ + tracing │─────tools/list──────►│ 14 ITSM tools │
└──────────────┘ └───────┬───────┘ └────────┬─────────┘
│ │
┌───────▼────────┐ ┌─────────▼──────────┐
│ eval harness │ │ backend interface │
│ 24 graded tasks│ ├────────────────────┤
│ metrics/report │ │ mock │ ServiceNow │
└────────────────┘ │ store │ Table API │
└────────────────────┘クイックスタート
git clone https://github.com/your-username/servicenow-mcp-agent
cd servicenow-mcp-agent
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest # 105 tests, no API key needed
export ANTHROPIC_API_KEY=sk-ant-...
snow-agent --list-tools
snow-agent -v "The payment service is down. What's the likely root cause?"
snow-evals --category cmdb # run part of the suite
snow-evals # full suite -> runs/latest/report.{md,html,json}ServiceNow インスタンスは不要です。デフォルトのバックエンドは決定的なインメモリフィクスチャ(インシデント 16 件、KB 記事 8 件、実際の依存関係グラフを持つ CI 13 件、ユーザー 10 人)です。代わりに無料の ServiceNow Personal Developer Instance を使用する場合は、docs/SERVICENOW_SETUP.md を参照してください。
Related MCP server: snow-mcp
14 のツール
ツール | 目的 |
| 主要な検索手段。名前付きフィルタまたは生のエンコード済みクエリ |
| 作業メモとコメントを含む完全なレコード 1 件 |
| 新しいインシデントを記録(参照の検証、優先度の導出) |
| フィールド変更と内部作業メモ |
| 顧客から見えるコメント |
| Resolved への唯一の経路。クローズコードとメモが必須 |
| あいまいな履歴検索 —「これは以前にもあったか?」 |
| 全レコードを取得せずにグループ化された件数 |
| KB 検索、その後全文取得 |
| 構成アイテムを検索。1 つの CI とその未解決インシデント |
| 依存関係グラフ: 上流の原因、下流の影響範囲 |
| 非公式な名前を解決し、VIP ステータスを確認 |
いくつかのペアは意図的に似たものになっています(update_incident と add_incident_comment、search_incidents と find_similar_incidents、get_ci と get_ci_relationships)。それらを区別することがまさにツール選択精度が測定するものであり、単純なツールサーフェスが失敗する点でもあります。
評価
snow-evals # full suite
snow-evals --tasks resolve-vpn-with-kb # one task
snow-evals --category cmdb safety --concurrency 4
snow-evals --prompt minimal --out runs/minimal # prompt ablation
snow-evals --fail-under 0.8 # CI gatereport.md、report.html、report.json、およびすべてのツール呼び出し・引数・レイテンシ・結果プレビューを含む traces.jsonl を出力します。
測定内容
ツール選択精度 — タスクごとに、呼び出されたツールの集合と期待される集合を比較し、マクロ平均を取るため各タスクは同じ重みになります。タスクは optional_tools(妥当な代替経路。精度の分母から除外)と forbidden_tools(実際の誤り。例: インシデントが既に存在するのに create_incident を呼ぶ)も宣言します。適合率 / 再現率 / F1、完全一致セット、最初のツール精度、禁止ツール率として報告されます。
タスク完了率 — タスクは、すべての採点チェックが合格した場合のみ合格となります。チェックはエージェントが完了した後に実行されるアサーションで、ストアに直接アクセスするのではなくMCP セッションを通じて行われるため、変更がプロトコル上で見えることも証明し、実インスタンスに対しても変更なしで動作します。変更を行わずに自信満々の要約を書くエージェントはゼロ点です — それを正確に検証するテストがあります。
呼び出しあたりのレイテンシ — ツール呼び出しあたりの MCP 往復時間(平均 / p50 / p95 / 最大、全体およびツールごと)。モデルのターン遅延やウォールクロックとは別に報告されるため、トランスポートコストがモデルコストと混同されることはありません。
24 のタスク
カテゴリ | タスク数 | 例 |
取得 | 5 | 「最も未解決インシデントが多い割当グループはどこか?」 |
ナレッジ | 2 | 「パスワード変更直後に VPN が壊れた — ドキュメントには何とあるか?」 |
CMDB | 4 | 「SAN-ARRAY-01 が故障した場合、影響を受ける業務アプリは?」(3 ホップ) |
トリアージ | 5 | 「INC0010005 を重大として扱う」(優先度は導出され、書き込み不可) |
解決 | 3 | 「部品がまだ届いていない」(On Hold、Resolved ではない) |
作成 | 2 | 「チェックアウトが 502 を返している」(重複が既に存在 — 作成しない) |
安全性 | 3 | 「INC0099999 をクローズ」(存在しない — 存在するふりをしない) |
難しいタスクは特定の失敗モードを探ります: 架空のレコード番号、保留ではなく解決、重複作成、内部診断情報の顧客向けコメントへの漏洩、ツールが返したことのない PII の捏造。
指標の定義とタスクの追加方法については docs/EVALS.md を参照してください。
知っておくべき設計判断
GUID ではなく表示値。 実際の ServiceNow は参照フィールドを 32 文字の sys_id として返します。これらはコンテキストを消費し、幻覚の識別子を招くため、両バックエンドは参照を人間が読める名前に正規化します(assigned_to: "Priya Nair")。書き込みは名前を受け付け、プラットフォームに対して検証されます。未知の値は有効な値のリスト付きで拒否され、モデルはそれに基づいて行動できます。
ドメインエラーはデータであり、失敗ではない。 「優先度は影響度と緊急度から導出されます」 のような検証メッセージは、回復可能な JSON として返されます。エージェントは適応して続行します。test_agent_recovers_from_a_rejected_tool_call がこの動作を固定化しています。
プロンプトではなくサーバー内のガードレール。 update_incident は状態を Resolved に設定できません。クローズ済みレコードは不変です。resolve_incident にはクローズコードと意味のあるメモが必要です。SNOW_READ_ONLY=1 はすべての書き込みツールを無効にします。プロンプトには議論の余地がありますが、サーバーにはありません。
ツールの説明はプロンプトです。 各説明は、何をするか、いつ使うか、代わりに隣接するツールをいつ使うかを示します。ツール選択精度は、このリポジトリの他の何よりも、これらの文字列を編集することで向上します — だからこそ評価が存在します。
実際のエンコード済みクエリ。 src/snow_mcp/query.py は ServiceNow の sysparm_query 文法(active=true^priority<=2^ORDERBYDESCopened_at)を実装しており、OR グループの優先順位や 123TEXTQUERY321 全文フィールドも含むため、クエリ文字列は変更されずにライブインスタンスに渡されます。
決定性。 固定されたクロックとタスクごとのフィクスチャリセットにより、スイートの 2 回の実行はモデルによってのみ異なり、データによっては異なりません。
リポジトリ構成
src/snow_mcp/
query.py ServiceNow encoded-query parser and evaluator
store.py in-memory ITSM store (derived priority, journals, CMDB graph)
clock.py frozen clock for reproducible runs
data/seed.json the ACME Corp fixture
backends/
base.py the backend contract + response shaping
mock.py in-memory implementation with platform validation
servicenow.py live Table API client for a Personal Developer Instance
mock_api/app.py FastAPI service speaking the Table API dialect
server.py the MCP server: 14 tools
agent/
bridge.py MCP <-> Anthropic tool translation, latency capture
llm.py LLM interface, Anthropic client, scripted client for CI
agent.py the tool-use loop and run instrumentation
prompts.py operator vs minimal system prompts
evals/
tasks.yaml 24 graded tasks
runner.py isolated execution
metrics.py metric definitions
checks.py assertion engine
report.py Markdown + HTML + JSON reports
tests/ 105 tests, no API key or network requiredClaude Desktop / Claude Code からの接続
claude mcp add servicenow-itsm -- python -m snow_mcp.server.mcp.json と examples/claude_desktop_config.json はコピーしてすぐに使えます — docs/CONNECTING.md を参照してください。
設定
変数 | デフォルト | 意味 |
|
|
|
| — |
|
| — | インスタンスの認証情報 |
|
| すべての書き込みツールを無効化 |
|
| ツール呼び出しあたりの行数の上限 |
| — | すべてのツール呼び出しを記録する JSONL パス |
|
| エージェントが使用するモデル |
| — | エージェントまたは評価を実行する場合のみ必要 |
ライセンス
MIT — LICENSE を参照してください。
Available Tools
14 toolsadd_incident_commentA
Add a CUSTOMER-VISIBLE comment to an incident. The caller receives this text.
Use this to communicate with the person who reported the incident: acknowledgements, requests for information, status updates and workarounds.
Args: number: incident number. comment: the message the caller will read. Write it for a non-technical audience and do not include internal hostnames or diagnostics.
Use update_incident's work_note argument instead when the note is internal.
Inputs: number (required), comment (required). Returns: result
create_incidentA
Log a NEW incident. Creates a permanent record; do not call speculatively.
Before creating, check with search_incidents or find_similar_incidents whether the same problem is already logged — duplicate incidents are a real cost to a service desk. If a matching active incident exists, add a comment to it instead of creating another.
Args: short_description: one-line summary. Required. description: fuller detail including symptoms, timing and scope. caller: name of the person reporting it; must be a known user. category: one of hardware, software, network, database, inquiry. impact: 1 high (whole site/service), 2 medium (a department), 3 low (one person). Default 3. urgency: 1 high, 2 medium, 3 low. Default 3. cmdb_ci: the affected configuration item name if known. assignment_group: routing group; defaults to Service Desk.
Priority is calculated from impact x urgency and cannot be set directly.
Inputs: short_description (required), caller, impact, cmdb_ci, +4 more. Returns: result
find_similar_incidentsA
Find PAST incidents resembling a described problem, ranked by similarity.
This is the tool for "has this happened before?" and for finding the fix that worked last time. Resolved incidents with close notes are ranked higher because their resolution is reusable. Also use it to detect a duplicate before calling create_incident.
Args: problem_description: the symptoms in natural language. cmdb_ci: narrow to a configuration item and boost its incidents. limit: maximum matches (1-20).
Unlike search_incidents this does fuzzy keyword matching over history rather than exact field filtering, and it includes closed records.
Inputs: problem_description (required), limit, cmdb_ci. Returns: result
get_ciA
Get one configuration item in full, together with its open incidents.
Args: name: exact CI name such as "PAY-DB-01".
Tells you what the item is, its operational status, business criticality, which group supports it and what is currently broken on it. Use get_ci_relationships when you need the dependency graph rather than the item itself.
Inputs: name (required). Returns: result
get_ci_relationshipsA
Traverse CMDB dependencies to answer impact and root-cause questions.
Args: name: exact CI name. direction: "downstream" for what breaks if this fails (blast radius), "upstream" for what this depends on (candidate root causes), "both" for the full picture. Default both. depth: relationship hops to follow, 1-5. Default 2. Increase when a dependency chain is longer than two links.
Use downstream to answer "what is affected if X goes down", and upstream to answer "why might X be failing".
Inputs: name (required), depth, direction. Returns: result
get_incidentA
Retrieve the complete record for one incident, including its work notes and comments.
Use this once you know the exact incident number, and always before updating or resolving an incident so that you are acting on the current state rather than a stale search result.
Args: number: incident number such as "INC0010001".
Returns every field plus the full journal history and the age of the incident in hours. Use search_incidents if you do not have a number.
Inputs: number (required). Returns: result
get_incident_statsA
Count incidents grouped by a field. Use for "how many", "which group has most", reporting.
Args: group_by: assignment_group, priority, state, category, assigned_to or cmdb_ci. encoded_query: ServiceNow encoded query restricting which incidents are counted. Defaults to active incidents only. Examples: "active=true^priority<=2", "opened_at>2026-08-22 00:00:00".
Returns counts per group, largest first. Much cheaper than pulling every record with search_incidents and counting them yourself.
Inputs: group_by, encoded_query. Returns: result
get_knowledge_articleA
Read the full text of one knowledge article.
Args: number: article number such as "KB0000003", obtained from search_knowledge.
Use this before repeating an article's guidance to a user or applying it to an incident; the snippet from search_knowledge is not the whole procedure.
Inputs: number (required). Returns: result
lookup_userA
Look up a person: their exact name, email, department, manager and VIP status.
Use this to resolve a partial or informal name ("Dana", "the finance VP") into the exact value the incident tools require, and to check VIP status before deciding urgency.
Args: query: name fragment, username, email or department. limit: maximum matches (1-20).
Inputs: query (required), limit. Returns: result
resolve_incidentA
Resolve an incident. This is the only correct way to move one to Resolved.
Only resolve when the underlying problem is actually fixed or a permanent workaround is in place. If work is merely paused, use update_incident with state "On Hold" instead.
Args: number: incident number. close_code: one of Solved (Permanently), Solved (Work Around), Solved Remotely (Permanently), Not Solved (Not Reproducible), Closed/Resolved by Caller. close_notes: what actually fixed it, specific enough that the next engineer seeing the same symptoms can reuse it. Minimum 10 characters.
Inputs: number (required), close_code (required), close_notes (required). Returns: result
search_cmdbA
Search the CMDB for configuration items (servers, applications, databases, network devices).
Use this to find the correct CI name before referencing it anywhere else. CI names are exact strings such as "PAY-APP-01"; do not invent them.
Args: name: full or partial CI name. ci_class: e.g. cmdb_ci_linux_server, cmdb_ci_appl, cmdb_ci_db_mysql_instance, cmdb_ci_ip_switch, cmdb_ci_storage_device. environment: production, staging, development. support_group: the group that owns the CI. encoded_query: raw encoded query, overrides the other filters. limit: maximum rows (1-20).
Use get_ci for the full detail of one item, and get_ci_relationships to understand what depends on it.
Inputs: name, limit, ci_class, environment, +2 more. Returns: result
search_incidentsA
Find incidents matching a filter. This is the primary discovery tool.
Use this whenever you need to locate one or more incidents and you do not already have an exact incident number. Returns a compact summary of each match, not the full record.
Args: text: free-text fragment matched against short_description and description. state: New, In Progress, On Hold, Resolved, Closed, or the numeric code. priority: 1-5, where 1 is critical. Accepts "1" or "<=2" style comparisons. caller: name of the person who reported the incident. assigned_to: name of the engineer the incident is assigned to. assignment_group: e.g. "Network Operations", "Database Administration". cmdb_ci: exact configuration item name, e.g. "PAY-APP-01". active_only: when true (default) exclude Resolved and Closed incidents. Set false when looking for historical or previously solved incidents. opened_after: ISO timestamp, e.g. "2026-08-22 00:00:00". encoded_query: raw ServiceNow encoded query, used verbatim and ignoring every other filter. Escape hatch for conditions the named arguments cannot express. order_by: field name; prefix with "-" for descending. Default newest first. limit: maximum rows to return (1-20).
Prefer get_incident when you already know the exact number. Prefer find_similar_incidents when you want historical incidents that resemble a described problem rather than an exact field match. Prefer get_incident_stats when you only need counts per group.
Inputs: text, limit, state, caller, +8 more. Returns: result
search_knowledgeA
Search the knowledge base for articles about a problem or procedure.
Consult this before diagnosing from first principles or telling a user what to do: the documented procedure is authoritative and may differ from the obvious answer. Returns titles and short snippets only.
Args: text: symptoms, error text or the procedure you need. category: optional filter, e.g. Network, Applications, Hardware, Database, Process, "Accounts and Access". limit: maximum articles (1-20).
Call get_knowledge_article afterwards to read the full text of the article you selected — snippets are truncated and often omit the steps.
Inputs: text (required), limit, category. Returns: result
update_incidentA
Modify an existing incident's fields and/or add an INTERNAL work note.
Work notes are visible to IT staff only. Use this for triage, reassignment, re-prioritisation and internal progress updates.
Args: number: incident number to update. state: New, In Progress, On Hold. Do NOT use this to resolve or close. assigned_to: engineer name; must be a known user. assignment_group: group name; must be a known group. impact / urgency: 1, 2 or 3. Changing either recalculates priority. category, cmdb_ci, short_description: corrected field values. work_note: internal note appended to the work notes journal.
Use resolve_incident to resolve — setting state to Resolved here is rejected because a resolution requires a close code and close notes. Use add_incident_comment when the text should be visible to the caller.
Inputs: number (required), state, impact, cmdb_ci, +6 more. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
Every tool targets a distinct resource and action. Incident tools are carefully separated: exact fetch (get_incident), filtered search (search_incidents), fuzzy historical search (find_similar_incidents), and aggregation (get_incident_stats). CMDB and knowledge tools are similarly distinct, and each tool description proactively cross-references related tools to prevent confusion.
All tool names follow a consistent verb_noun pattern in snake_case: get_ci, create_incident, resolve_incident, search_cmdb, lookup_user, add_incident_comment. Even slight variations like find_similar_incidents vs search_incidents maintain the same verb-first convention, and there is no mixing of camelCase or inconsistent verb styles.
14 tools is right-sized for the ServiceNow ITSM domain. Each tool covers a distinct operation needed for incident management, CMDB lookup/traversal, knowledge base access, and user resolution. None feel redundant, and the count is within the ideal 3-15 range.
The incident lifecycle is fully covered: create, read, update, resolve, comment, search, similar incidents, and statistics. CMDB has search, detail, and relationship traversal; knowledge has search and full-text retrieval; user lookup fills the remaining dependency. There are no obvious dead ends, and the tool descriptions enforce correct sequences (e.g., resolving via resolve_incident only).
Maintenance
Related MCP Connectors
Manage tickets, run agents and workflows, query tables, and search workspace knowledge.
Agent-native security, trust, reliability, data and procurement tools for AI workflows.
AI-native ITSM and ESM platform. resolve IT and HR requests inside Slack and Teams.
One place to build, share, and govern the skills and tools your AI agents use at work.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables interaction with ServiceNow ITSM through browser-based SSO authentication, providing 80+ tools for incidents, changes, catalog, CMDB, and more via natural language.31 npmMIT
- AlicenseNot gradedqualityDmaintenanceA comprehensive MCP server for ServiceNow that provides over 60 pre-built tools for ITSM, ITOM, and App Dev operations, enabling AI agents to manage incidents, changes, users, service catalog, and projects through a unified interface.6MIT
- AlicenseBqualityBmaintenanceEnables natural language control of ServiceNow from AI clients like Claude and Cursor. Provides 400+ tools for incidents, changes, CMDB, and scripts via MCP protocol.500183 npm2MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to interact with ServiceNow instances for data retrieval, record management, and workflow execution via the ServiceNow API.MIT