ServiceNow MCP Demo — Incident Assistant

Eine End-to-End-Demo zum Model Context Protocol, die Claude mit ServiceNow Incident Management verbindet. Entwickelt, um MCP-Grundlagen (Server, Clients, Tools, Ressourcen, stdio-Transport, Agent-Loops) anhand eines echten ITSM-Workflows zu veranschaulichen.

Architektur

┌─────────────────────────────┐        ┌───────────────────────────────┐        ┌────────────────┐
│  Web Client (Streamlit)     │  MCP   │  MCP Server (FastMCP)         │  REST  │  ServiceNow    │
│  - MCP host + client        │◄──────►│  - create_incident            │◄──────►│  Table API     │
│  - Claude agent loop        │ stdio  │  - get_incident               │        │  (or mock mode)│
│  - Incident cards in UI     │JSON-RPC│  - list_recent_incidents      │        │                │
│                             │        │  - update_incident_state      │        │                │
│                             │        │  - resolve_incident           │        │                │
│                             │        │  - search_knowledge_articles  │        │                │
│                             │        │  - resource: priority         │        │                │
│                             │        │    matrix reference           │        │                │
└─────────────────────────────┘        └───────────────────────────────┘        └────────────────┘

Der Ablauf für „Mein Laptop bootet nicht, öffne ein Ticket“:

1. Der Web-Client sendet deine Nachricht zusammen mit den Tool-Schemas an Claude, die er beim Start vom MCP-Server entdeckt hat (tools/list).

2. Claude entscheidet sich, create_incident mit abgeleiteter Dringlichkeit/Auswirkung/Kategorie aufzurufen.

3. Der Client leitet den Aufruf über MCP weiter (tools/call); der Server ruft die ServiceNow Table API (oder den In-Memory-Mock) auf.

4. Das Ergebnis fließt zurück; Claude bestätigt die Incident-Nummer; die UI rendert eine Incident-Karte.

Related MCP server: ServiceNow MCP Server (SSE)

Schnellstart

# 1. Create a virtual environment
python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate

# 2. Install dependencies
pip install -r requirements.txt

# 3. Configure
cp .env.example .env             # then edit: add your ANTHROPIC_API_KEY
                                 # leave SERVICENOW_MODE=mock for a no-setup demo

# 4. Run the web client (it launches the MCP server automatically)
streamlit run client/app.py

Öffne http://localhost:8501 und probiere Folgendes:

• „Mein Laptop bootet nicht und ich habe in einer Stunde eine Kundendemo — öffne ein Ticket.“

• „Zeig mir die 5 neuesten Incidents.“

• „Verschiebe INC0010001 auf In Progress mit einer Work Note, dass der Techniker unterwegs ist.“

• „Gibt es KB-Artikel zu einem Laptop, der sich nicht einschalten lässt?“

• „Das hat es behoben — löse INC0010001 auf, dauerhaft gelöst, das Ladegerät wurde ersetzt.“

Live-ServiceNow-Modus

1. Fordere eine kostenlose Personal Developer Instance (PDI) unter https://developer.servicenow.com an (dauert ~2 Minuten).

2. Setze in .env SERVICENOW_MODE=live und fülle SERVICENOW_INSTANCE, SERVICENOW_USER, SERVICENOW_PASSWORD aus.

3. Starte die App neu. Erstellte Incidents erscheinen in deiner PDI unter Incident > All — ideal, um das Ticket während der Demo in der echten ServiceNow-UI zu präsentieren.

PDIs schlafen nach Inaktivität ein. Weck sie ~15 Minuten vor deinem Vorstellungsgespräch auf und behalte den mock-Modus als Fallback.

search_knowledge_articles fragt die kb_knowledge-Tabelle der PDI direkt ab — lege vor der Demo im Live-Modus 2–3 veröffentlichte KB-Artikel dort an, deren Titel zu deinem Demo-Szenario passen (z. B. „Laptop lässt sich nicht einschalten“), sonst kommt die Live-Suche leer zurück. Der Mock-Modus bringt bereits 3 vorab angelegte Artikel mit und ist damit sofort einsatzbereit.

Den Server eigenständig testen (ohne UI)

Der MCP Inspector ist der schnellste Weg, um zu beweisen, dass der Server eigenständig funktioniert:

npx @modelcontextprotocol/inspector python server/servicenow_server.py

Du kannst den Server auch zu Claude Desktop hinzufügen (claude_desktop_config.json):

{
  "mcpServers": {
    "servicenow": {
      "command": "python",
      "args": ["/absolute/path/to/server/servicenow_server.py"]
    }
  }
}

Projektstruktur

servicenow-mcp-demo/
├── server/servicenow_server.py   # FastMCP server: 6 tools + 1 resource, mock/live backends
├── client/app.py                 # Streamlit web app: MCP client + Claude agent loop
├── requirements.txt
├── .env.example
├── PROJECT_PLAN.md               # Phase-by-phase build plan and status
└── DEMO_SCRIPT.md                # 5-minute recorded-demo script

Demonstrierte MCP-Konzepte

• Server erstellt mit FastMCP: Tools mit typisierten Parametern und Docstring-basierten Schemas

• Resource (servicenow://reference/priority-matrix) — schreibgeschützter Kontext im Unterschied zu Tools

• stdio-Transport — der Client startet den Server-Subprozess und spricht JSON-RPC

• Capability Discovery — der Client hardcodiert Tools nie; er ruft tools/list auf

• Agent-Loop — Tool-Nutzung über mehrere Runden mit Claude, bis eine endgültige Textantwort vorliegt

• Separation of Concerns — derselbe Server funktioniert unverändert mit diesem Web-Client, Claude Desktop oder dem MCP Inspector