ServiceNow Story MCP – Python-Client
Ein Kommandozeilen-Client für die vier ServiceNow-Story-Tools. Voraussetzung: Python 3.10 oder neuer und Microsoft Edge für den ersten OAuth-Login. Die OAuth-Registrierung muss als Redirect http://127.0.0.1:8765/oauth/callback enthalten; Browser und Client müssen auf demselben Rechner laufen.
Installation
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
Unter Windows: py -m venv .venv und .venv\Scripts\activate. Unter Debian/Ubuntu kann für venv das entsprechende Paket python3-venv fehlen. Alternativ lässt sich ohne virtuelle Umgebung lokal installieren:
python3 -m pip install --target .python-deps -r requirements.txt
PYTHONPATH=.python-deps python3 story_client.py tools
Anmelden und verwenden
Die Datei clientsecret im Arbeitsverzeichnis enthält das Client-Secret. Alternativ OAUTH_CLIENT_SECRET_FILE auf die Datei oder OAUTH_CLIENT_SECRET auf den Wert setzen. chmod 600 clientsecret schränkt unter Linux den Zugriff ein. Geheimnisse und Tokens nicht einchecken.
python story_client.py tools
python story_client.py list '{"limit":"5"}'
python story_client.py list '{"query":"active=true^priority=1"}'
python story_client.py get SYS_ID
python story_client.py create '{"short_description":"MCP Test Story","type":"Development","product":"PRODUCT_SYS_ID"}'
python story_client.py update SYS_ID '{"story_points":"3"}'
Bei Bedarf öffnet der Client Microsoft Edge für die Anmeldung und empfängt den OAuth-Code lokal. Er sucht Edge in den üblichen Installationspfaden bzw. im PATH. Mit EDGE_PATH kann der vollständige Programmpfad angegeben werden. Ein anderer Browser wird nicht automatisch verwendet. Port 8765 muss frei sein. Der Client speichert Tokens in .tokens.json mit Dateirechten 0600 auf Unix und erneuert sie automatisch; die vorhandene Token-Datei des JavaScript-Clients kann weiterverwendet werden. Ein widerrufener oder abgelaufener Refresh-Token führt zu einer erneuten Edge-Anmeldung. Um ein anderes Konto zu verwenden, eine andere Datei mit OAUTH_TOKEN_FILE wählen.
create und update verpacken die Felder automatisch in request_body, entsprechend dem vom Server gemeldeten Schema. Für direkte MCP-Aufrufe wird das vollständige Tool-Argument übergeben, zum Beispiel:
python story_client.py call rm_story_create '{"request_body":{"short_description":"MCP Test Story","type":"Development","product":"PRODUCT_SYS_ID"}}'
Die Ausgabe ist die MCP-Antwort als JSON. Ein Toolfehler setzt einen Exit-Code ungleich null. tools prüft die vier erwarteten Tool-Namen. Create und Update ändern echte ServiceNow-Daten; für Referenzfelder sys_id verwenden. Es gibt keinen Delete-Befehl.
Optionen: --transport sse für einen SSE-Server (ggf. MCP_URL ändern), MCP_URL, OAUTH_CLIENT_ID, OAUTH_REDIRECT_URI und OAUTH_TOKEN_FILE. Eine geänderte Callback-URL muss exakt auf dem Server registriert sein und HTTP auf 127.0.0.1 mit festem Port verwenden. OAuth-Endpunkte werden per Discovery ermittelt; falls das fehlschlägt, werden die bekannten ServiceNow-Endpunkte verwendet.
Tests: python -m unittest discover -s tests -v.
Echter Integrationstest
python scripts/integration_test.py --product PRODUCT_SYS_ID
Der Test verwendet die echte ServiceNow-Instanz, erneuert das gespeicherte Token und prüft Tool-Liste, Lesen, Filter, Einzelabruf und Negativfälle. Danach versucht er, eine mit MCP Integrationstest und Zeitstempel gekennzeichnete Story zu erstellen, zu lesen, story_points zu ändern und die Änderung erneut zu lesen. Eine erfolgreich angelegte Test-Story bleibt bestehen, da kein Delete-Tool angeboten wird. Der Test gibt ihre sys_id aus. Bei einem Fehler endet er mit Exit-Code 1 und überspringt abhängige Schritte.
Auf dieser Instanz verlangt eine Data Policy beim Anlegen zusätzlich product: Die Produkt-sys_id muss ausdrücklich angegeben werden. Der Integrationstest wurde inklusive Create, Lesen, Update und erneutem Lesen erfolgreich ausgeführt. Die benutzte Produkt-sys_id muss zur vorgesehenen Test-Story passen.
Lokaler MCP-Proxy für Codex
Den Proxy im Projektverzeichnis starten und während der Nutzung laufen lassen:
PYTHONPATH=.python-deps python3 mcp_proxy.py
# oder mit aktivierter virtueller Umgebung:
python mcp_proxy.py
Er verwendet dieselben OAuth-Einstellungen, das Secret und die Token-Datei wie der Kommandozeilen-Client. Falls ein Login nötig ist, muss Microsoft Edge auf dem Rechner verfügbar sein; EDGE_PATH kann seinen Pfad angeben. Den Proxy mit Strg+C beenden. Ein anderer lokaler Port ist über --port wählbar.
In der MCP-Konfiguration von Codex:
- Name:
ServiceNow Stories Proxy - Typ:
Streamable HTTP - URL:
http://127.0.0.1:8766/mcp - Bearer-Token-Umgebungsvariable und Header: leer lassen.
Die vier Tool-Schemas, Argumente und Ergebnisse inklusive Fehler werden an den ServiceNow-Server durchgereicht. Der Proxy bindet ausschließlich an 127.0.0.1 und benötigt lokal selbst kein Token. Andere Prozesse auf demselben Rechner können den Proxy ebenfalls verwenden und damit unter deiner ServiceNow-Identität Stories lesen und ändern, solange er läuft. Deshalb nur auf einem vertrauenswürdigen Rechner ausführen und nach Gebrauch beenden. Der Proxy ist für lokale Codex-Prozesse gedacht; eine in der Cloud laufende ChatGPT-Sitzung erreicht 127.0.0.1 auf deinem Rechner nicht direkt.