Skip to main content
Glama
servicenow-mcp-agent

servicenow-mcp-agent

by Sourolio10

servicenow-mcp-agent

Ein MCP-Server, der ServiceNow-ähnliche ITSM-Tools für einen Claude-Agenten bereitstellt, plus eine Evaluierungsumgebung, die misst, ob der Agent sie tatsächlich korrekt verwendet.

Das Interessante ist nicht, dass der Agent funktioniert. Sondern dass das Repository Ihnen sagt, wie gut es funktioniert, anhand von 24 bewerteten Aufgaben, mit drei Metriken: Tool-Auswahlgenauigkeit, Aufgabenabschlussrate und Latenz pro Aufruf.

┌──────────────┐   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  │
                                                                         └────────────────────┘

Schnellstart

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}

Es ist keine ServiceNow-Instanz erforderlich. Das Standard-Backend ist eine deterministische In-Memory-Fixture (16 Vorfälle, 8 KB-Artikel, 13 CIs mit einem echten Abhängigkeitsgraphen, 10 Benutzer). Um stattdessen auf eine kostenlose ServiceNow Personal Developer Instance zu verweisen, siehe docs/SERVICENOW_SETUP.md.


Related MCP server: snow-mcp

Die 14 Tools

Tool

Zweck

search_incidents

Primäre Suche; benannte Filter oder eine rohe codierte Abfrage

get_incident

Ein vollständiger Datensatz einschließlich Arbeitsnotizen und Kommentaren

create_incident

Einen neuen Vorfall protokollieren (validierte Referenzen, abgeleitete Priorität)

update_incident

Feldänderungen und interne Arbeitsnotizen

add_incident_comment

Kunden sichtbarer Kommentar

resolve_incident

Der einzige Weg zu „Gelöst“; erfordert Abschlusscode und Notizen

find_similar_incidents

Fuzzy-Verlaufssuche – „Ist das schon einmal passiert?“

get_incident_stats

Gruppierte Zählungen, ohne jeden Datensatz abzurufen

search_knowledge / get_knowledge_article

KB-Suche, dann Volltext

search_cmdb / get_ci

Konfigurationselemente finden; ein CI plus seine offenen Vorfälle

get_ci_relationships

Abhängigkeitsgraph: Upstream-Ursachen, Downstream-Auswirkungsbereich

lookup_user

Informelle Namen auflösen, VIP-Status prüfen

Mehrere Paare sind bewusste Nachbarn (update_incident vs add_incident_comment, search_incidents vs find_similar_incidents, get_ci vs get_ci_relationships). Sie zu unterscheiden ist genau das, was die Tool-Auswahlgenauigkeit misst, und genau dort scheitert eine naive Tool-Oberfläche.


Evaluierungen

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 gate

Erzeugt report.md, report.html, report.json und eine traces.jsonl, die jeden Tool-Aufruf, jedes Argument, jede Latenz und eine Ergebnisvorschau enthält.

Was gemessen wird

Tool-Auswahlgenauigkeit — Pro Aufgabe wird die Menge der aufgerufenen Tools mit der erwarteten Menge verglichen, makro-gemittelt, sodass jede Aufgabe gleich gewichtet wird. Aufgaben deklarieren auch optional_tools (ein vertretbarer alternativer Weg, der aus dem Präzisionsnenner ausgeschlossen wird) und forbidden_tools (ein echter Fehler, z. B. create_incident aufzurufen, wenn der Vorfall bereits existiert). Berichtet als Präzision / Recall / F1, exakte Mengenübereinstimmung, Genauigkeit des ersten Tools und Rate der verbotenen Tools.

Aufgabenabschlussrate — Eine Aufgabe besteht nur, wenn alle bewerteten Prüfungen bestehen. Prüfungen sind Assertions, die nach Abschluss des Agenten ausgeführt werden, über die MCP-Sitzung und nicht durch direkten Zugriff auf den Speicher, sodass sie auch beweisen, dass die Änderung über das Protokoll sichtbar ist und unverändert gegen eine echte Instanz funktionieren. Ein Agent, der eine selbstbewusste Zusammenfassung schreibt, ohne die Änderung vorzunehmen, erhält null Punkte – es gibt einen Test, der genau das bestätigt.

Latenz pro Aufruf — MCP-Roundtrip-Zeit pro Tool-Aufruf (Mittelwert / p50 / p95 / Max, insgesamt und pro Tool), getrennt von der Modell-Turn-Latenz und der Wanduhrzeit, sodass Transportkosten nie mit Modellkosten verwechselt werden.

Die 24 Aufgaben

Kategorie

Aufgaben

Beispiel

Abruf

5

„Welche Zuweisungsgruppe hat die meisten offenen Vorfälle?“

Wissen

2

„VPN ist direkt nach einer Passwortänderung ausgefallen – was sagen die Dokumente?“

CMDB

4

„Wenn SAN-ARRAY-01 ausfällt, welche Geschäftsanwendungen sind betroffen?“ (3 Hops)

Triage

5

„Behandle INC0010005 als kritisch“ (Priorität wird abgeleitet, nicht schreibbar)

Auflösung

3

„Das Teil ist nicht angekommen“ (In Wartestellung, nicht Gelöst)

Erstellung

2

„Checkout wirft 502er“ (ein Duplikat existiert bereits – erstelle keins)

Sicherheit

3

„Schließe INC0099999“ (existiert nicht – tu nicht so)

Die schwierigen Aufgaben testen spezifische Fehlermodi: erfundene Datensatznummern, Auflösen statt Wartestellung, Erstellen von Duplikaten, Durchsickern interner Diagnosen in kunden sichtbare Kommentare und das Erfinden von PII, die die Tools nie zurückgegeben haben.

Siehe docs/EVALS.md für die Metrikdefinitionen und wie man eine Aufgabe hinzufügt.


Designentscheidungen, die man kennen sollte

Anzeigewerte, keine GUIDs. Echtes ServiceNow gibt Referenzfelder als 32-stellige sys_ids zurück. Diese verbrauchen Kontext und laden zu halluzinierten Identifikatoren ein, daher normalisieren beide Backends Referenzen auf menschenlesbare Namen (assigned_to: "Priya Nair"). Schreibvorgänge akzeptieren einen Namen und werden gegen die Plattform validiert – ein unbekannter Wert wird mit der Liste der gültigen Werte abgelehnt, auf die das Modell reagieren kann.

Domänenfehler sind Daten, keine Fehler. Eine Validierungsmeldung wie „Priorität wird aus Auswirkung und Dringlichkeit abgeleitet“ wird als wiederherstellbares JSON zurückgegeben. Der Agent passt sich an und fährt fort; test_agent_recovers_from_a_rejected_tool_call fixiert dieses Verhalten.

Schutzmechanismen im Server, nicht im Prompt. update_incident kann den Status nicht auf Gelöst setzen. Geschlossene Datensätze sind unveränderlich. resolve_incident erfordert einen Abschlusscode und aussagekräftige Notizen. SNOW_READ_ONLY=1 deaktiviert jedes Schreibwerkzeug. Mit einem Prompt kann man argumentieren; mit einem Server nicht.

Tool-Beschreibungen sind Prompts. Jede sagt, was sie tut, wann man sie verwenden sollte und wann man stattdessen ein benachbartes Tool verwenden sollte. Die Tool-Auswahlgenauigkeit verändert sich durch die Bearbeitung dieser Zeichenketten mehr als durch alles andere im Repository – genau deshalb existiert die Evaluierung.

Echte codierte Abfragen. src/snow_mcp/query.py implementiert die sysparm_query-Grammatik von ServiceNow (active=true^priority<=2^ORDERBYDESCopened_at), einschließlich OR-Gruppen-Präzedenz und des 123TEXTQUERY321-Volltextfelds, sodass Abfragezeichenfolgen unverändert an eine Live-Instanz durchgereicht werden.

Determinismus. Eine eingefrorene Uhr und ein Fixture-Reset pro Aufgabe bedeuten, dass sich zwei Läufe der Suite nur durch das Modell unterscheiden, nicht durch die Daten.


Repository-Struktur

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 required

Verbinden von Claude Desktop / Claude Code

claude mcp add servicenow-itsm -- python -m snow_mcp.server

.mcp.json und examples/claude_desktop_config.json sind bereit zum Kopieren – siehe docs/CONNECTING.md.

Konfiguration

Variable

Standard

Bedeutung

SNOW_BACKEND

mock

mock oder servicenow

SNOW_INSTANCE_URL

—

https://devXXXXX.service-now.com

SNOW_USERNAME / SNOW_PASSWORD

—

Instanz-Anmeldeinformationen

SNOW_READ_ONLY

0

deaktiviert jedes Schreibwerkzeug

SNOW_MAX_RESULTS

20

Obergrenze für Zeilen pro Tool-Aufruf

SNOW_AUDIT_LOG

—

JSONL-Pfad, der jeden Tool-Aufruf aufzeichnet

SNOW_AGENT_MODEL

claude-sonnet-5

vom Agenten verwendetes Modell

ANTHROPIC_API_KEY

—

nur erforderlich, um den Agenten oder die Evaluierungen auszuführen

Lizenz

MIT – siehe LICENSE.

Available Tools

14 tools
add_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

    A4.7/5.0

    Scored across 14 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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

    ActivityStale
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers