servicenow-mcp

Ein kleiner MCP-Server, der KI-Agenten das Erstellen, Suchen und Aktualisieren von ServiceNow-Vorfällen über die Table-API ermöglicht. Erstellt mit dem offiziellen Python-Paket mcp (FastMCP-ähnliche Dekorateure), httpx und python-dotenv. Läuft über stdio.

Alles befindet sich in einer einzigen Datei: server.py.

Einrichtung

Erfordert Python 3.12+ und uv.

uv sync

Erstellen Sie eine .env-Datei neben server.py (sie wird von git ignoriert) mit Basic-Auth-Anmeldedaten für Ihre Instanz – eine Personal Developer Instance funktioniert gut:

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

Führen Sie den Server aus (er spricht MCP über stdin/stdout, daher gibt es nichts zu sehen – ein MCP-Client muss ihn starten):

uv run server.py

Registrieren bei einem MCP-Client

Weisen Sie den Client auf uv mit dem Projektverzeichnis hin, damit .venv und .env erkannt werden:

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

Für Claude Code: claude mcp add servicenow -- uv --directory /absolute/path/to/servicenow-mcp run server.py.

Umgebungsvariablen, die bereits in der Umgebung des Clients gesetzt sind, haben Vorrang vor .env.

Related MCP server: sn-mcp-bridge

Werkzeuge

Alle Werkzeuge lösen einen lesbaren Werkzeugfehler aus (dem Agenten als isError gemeldet) anstatt eines Stack-Trace, z.B.:

• 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-Notizen

• ServiceNowClient kapselt einen einzelnen httpx.AsyncClient (Basic-Auth, JSON-Header, Timeout) und stellt create_record / query_records / get_record_by_number / update_record bereit. Alle Fehler werden in ServiceNowError mit einer menschenlesbaren Nachricht übersetzt.

• Die Werkzeuge erhalten den Client über get_client(); rufen Sie in Tests set_client(fake) auf, um einen Mock auszutauschen, ohne das Netzwerk zu berühren.

• Datensätze werden mit sysparm_display_value=all abgerufen, sodass Status-/Dringlichkeitsbezeichnungen von der Instanz selbst stammen und nicht aus einer fest codierten Zuordnung (die freundlichen Namensaliasse sind nur für die Eingabe).

• mcp 2.x hat FastMCP in MCPServer umbenannt; server.py importiert dasjenige, das existiert, sodass es sowohl auf 1.x als auch auf 2.x läuft.

Rauchtest

Gegen die Live-Instanz ausführen (schreibt einen Vorfall):

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())
"