sn-mcp-bridge

Ein leichter Model Context Protocol (MCP)-Server, der KI-Coding-Assistenten die volle Entwicklungsumgebung auf ServiceNow bietet – ohne Installation auf der Plattform. Er läuft lokal über npx und verbindet sich über die Table-API mit ServiceNow.

ServiceNow ist eine datensatzbasierte Entwicklungsplattform. Script Includes, Business Rules, Client Scripts, UI Actions, ACLs – jedes Entwicklungsartefakt ist ein Datensatz in einer Systemtabelle. Es gibt keine separate "Code-Ebene"; die Table-API ist die Entwicklungs-API. Das bedeutet, CRUD-Operationen über diesen Server dienen nicht nur zum Abfragen von Daten – sie sind die Art und Weise, wie Sie entwickeln:

• insert_record in sys_script_include → erstellt ein neues Script Include

• update_record auf sys_script → ändert eine Business Rule

• query_data auf sys_script_client → liest alle Client Scripts für eine Tabelle

• delete_record auf sys_ui_action → entfernt eine UI Action

Für Aufgaben, die über CRUD hinausgehen – Testen von Logik, Ausführen komplexer GlideRecord-Abfragen, Aufrufen von Script Includes oder mehrstufige Transaktionen – bietet execute_script eine vollständige serverseitige JavaScript-Laufzeitumgebung.

Der Server läuft mit den Berechtigungen des Benutzerkontos, für das Sie Anmeldedaten angeben – er kann nur Tabellen und Felder lesen/schreiben, auf die dieser Benutzer Zugriff hat. Das Tool execute_script erfordert Admin-Anmeldedaten, da es Hintergrundskripte über sys.scripts.do ausführt.

Die Authentifizierung unterstützt sowohl Basic Auth als auch OAuth 2.0 (Autorisierungscode) – siehe Authentifizierung.

Es gibt viele Open-Source-ServiceNow-MCP-Server, die in der Community geteilt werden. Dieser existiert, um einfach, pur und leicht verbesserbar zu bleiben – reines JS ohne Build-Schritt (4 Quelldateien, natives fetch, Node.js 18+), und das Hinzufügen eines Tools erfolgt mit einem server.registerTool()-Aufruf.

Tools

CRUD

Schema & Discovery

Analytik

Erweitert

Diagnose

¹ Diese vier Tools erfordern einen Benutzernamen und ein Passwort – siehe Authentifizierung. Sie werden nicht registriert, wenn nur OAuth-Anmeldedaten konfiguriert sind.

Related MCP server: ServiceNow MCP Server

Authentifizierung

Die Bridge unterstützt zwei Modi. Sie wählt OAuth, wenn CLIENT_ID, CLIENT_SECRET und GRANT_TYPE gesetzt sind; andernfalls verwendet sie Basic Auth.

Alle Variablen folgen derselben Namenskonvention: <INSTANCE_NAME> ist die Subdomain von SN_INSTANCE, in Großbuchstaben und mit Unterstrichen anstelle von Bindestrichen (z. B. https://mydev01.service-now.com → SN_MYDEV01_USERNAME). Wenn eine präfixierte Variable nicht gesetzt ist, fällt die Bridge auf die nicht präfixierte Form zurück (SN_USERNAME, SN_CLIENT_ID, …).

Basic Auth

Warnung: Die folgenden Beispiele verwenden Klartext-Anmeldedaten, um Ihnen einen schnellen Start zu ermöglichen. Das bedeutet, dass Ihr Passwort in einer Datei auf der Festplatte gespeichert und dem KI-Assistenten in jedem API-Aufruf an den LLM-Anbieter sichtbar ist. Sobald Sie bestätigt haben, dass die Verbindung funktioniert, wird dringend empfohlen, die Anweisungen unter Sichern von Anmeldedaten mit Secretless AI zu befolgen, um Klartext-Geheimnisse aus Ihrer Konfiguration zu entfernen!

OAuth 2.0 (Autorisierungscode)

OAuth hält Ihr ServiceNow-Passwort vollständig aus der Konfiguration heraus. Die Bridge autorisiert einmal über Ihren Browser und erneuert dann selbstständig ein kurzlebiges Zugriffstoken.

1. Registrieren Sie eine OAuth-Anwendung in ServiceNow. Navigieren Sie zu System OAuth → Application Registry, klicken Sie auf Neu und wählen Sie OAuth-API-Endpunkt für externe Clients erstellen. Geben Sie einen Namen ein, setzen Sie die Weiterleitungs-URL auf http://localhost:33380/callback und speichern Sie. Kopieren Sie die generierte Client-ID und das Client-Geheimnis.

2. Konfigurieren Sie die Bridge:

Das Setzen einer der Variablen CLIENT_ID / CLIENT_SECRET / GRANT_TYPE ohne die anderen führt zu einem Startfehler und nicht zu einem stillen Fallback auf Basic Auth.

3. Erster Start. Die Bridge öffnet Ihren Browser zur Zustimmungsseite der Instanz (die URL wird auch auf stderr ausgegeben, falls dies nicht möglich ist). Nach Ihrer Zustimmung erfasst sie die Weiterleitung auf localhost:33380 und tauscht den Code gegen Token ein.

Der erste Start blockiert bis zu drei Minuten, während Sie im Browser zustimmen. Wenn Ihr MCP-Client eine Zeitüberschreitung hat, bevor Sie fertig sind, wurden die Token normalerweise bereits geschrieben – stellen Sie einfach die Verbindung wieder her, und es startet still.

Token-Speicherung. Token werden in ~/.sn-mcp-bridge/tokens.json zwischengespeichert (Verzeichnis 0700, Datei 0600), abgelegt nach Instanz-Host und Client-ID, sodass mehrere Instanzen in einer Datei koexistieren. Nachfolgende Starts verwenden das zwischengespeicherte Refresh-Token ohne Browser-Interaktion erneut. Wenn das Refresh-Token abläuft (standardmäßig 100 Tage bei ServiceNow), wird der Browser-Fluss automatisch erneut ausgelöst. Löschen Sie die Datei, um eine erneute Autorisierung zu erzwingen.

Verwendung beider Methoden zusammen

OAuth deckt nur die REST/Table-API ab. execute_script, explore_syslog, explore_syslog_transaction und explore_node_logs greifen auf ServiceNow-UI-Endpunkte (sys.scripts.do, ui_page_process.do) zu, die eine Formular-Login-Sitzung benötigen, die ein Bearer-Token nicht bereitstellen kann.

Wenn Sie USERNAME und PASSWORD zusätzlich zu den OAuth-Variablen angeben, erfolgt der REST-Verkehr über OAuth, und diese vier Tools verwenden die Anmeldedaten für ihre Sitzungsanmeldung. Wenn Sie dies nicht tun, werden die vier Tools einfach nicht registriert – der Assistent sieht sie nie.

Schnellstart

Claude Code

Fügen Sie in Ihrem Projektstammverzeichnis (nur in diesem Projekt verfügbar) zu .mcp.json oder zu ~/.claude/claude_code_config.json (in allen Projekten verfügbar) hinzu:

{
	"mcpServers": {
		"sn_mydev01": {
			"command": "npx",
			"args": ["-y", "sn-mcp-bridge"],
			"env": {
				"SN_INSTANCE": "https://mydev01.service-now.com",
				"SN_MYDEV01_USERNAME": "your_username",
				"SN_MYDEV01_PASSWORD": "your_password"
			}
		}
	}
}

OpenAI Codex

Fügen Sie in Ihrem Projektstammverzeichnis (nur für das Projekt, erfordert ein vertrauenswürdiges Projekt) zu .codex/config.toml oder zu ~/.codex/config.toml (in allen Projekten verfügbar) hinzu:

[mcp_servers.sn_mydev01]
command = "npx"
args = ["-y", "sn-mcp-bridge"]

[mcp_servers.sn_mydev01.env]
SN_INSTANCE = "https://mydev01.service-now.com"
SN_MYDEV01_USERNAME = "your_username"
SN_MYDEV01_PASSWORD = "your_password"

VS Code (GitHub Copilot)

Fügen Sie in Ihrem Projekt zu .vscode/mcp.json hinzu:

{
	"servers": {
		"sn_mydev01": {
			"type": "stdio",
			"command": "npx",
			"args": ["-y", "sn-mcp-bridge"],
			"env": {
				"SN_INSTANCE": "https://mydev01.service-now.com",
				"SN_MYDEV01_USERNAME": "your_username",
				"SN_MYDEV01_PASSWORD": "your_password"
			}
		}
	}
}

Cursor

Fügen Sie in Ihrem Projekt zu .cursor/mcp.json hinzu:

{
	"mcpServers": {
		"sn_mydev01": {
			"command": "npx",
			"args": ["-y", "sn-mcp-bridge"],
			"env": {
				"SN_INSTANCE": "https://mydev01.service-now.com",
				"SN_MYDEV01_USERNAME": "your_username",
				"SN_MYDEV01_PASSWORD": "your_password"
			}
		}
	}
}

Verwendung von OAuth stattdessen

Ersetzen Sie das Paar aus Benutzername/Passwort durch die OAuth-Variablen. Der env-Block unten gilt für jeden oben genannten Editor – nur die umgebende Konfigurationssyntax unterscheidet sich:

{
	"mcpServers": {
		"sn_mydev01": {
			"command": "npx",
			"args": ["-y", "sn-mcp-bridge"],
			"env": {
				"SN_INSTANCE": "https://mydev01.service-now.com",
				"SN_MYDEV01_CLIENT_ID": "your_client_id",
				"SN_MYDEV01_CLIENT_SECRET": "your_client_secret",
				"SN_MYDEV01_GRANT_TYPE": "authorization_code"
			}
		}
	}
}

Um execute_script und die Diagnosetools verfügbar zu halten, fügen Sie SN_MYDEV01_USERNAME und SN_MYDEV01_PASSWORD zu demselben Block hinzu – siehe Verwendung beider Methoden zusammen.

Mehrere Instanzen

Fügen Sie für jede Instanz einen separaten Servereintrag hinzu. Das Konfigurationsformat ist dasselbe wie oben – wiederholen Sie einfach das Muster mit einem anderen Servernamen und instanzspezifischen Anmeldedaten.

Sichern von Anmeldedaten mit Secretless AI

Secretless AI speichert Ihre Anmeldedaten in einem sicheren Backend und injiziert sie zur Laufzeit über secretless-ai run.

Die folgenden Beispiele sichern einen Benutzernamen und ein Passwort, aber derselbe Ansatz funktioniert für SN_MYDEV01_CLIENT_SECRET, wenn Sie OAuth verwenden.

Einrichtung

1. Speichern Sie Ihre Anmeldedaten:

npx secretless-ai secret set SN_MYDEV01_USERNAME=your_username

# Omit the value so it prompts interactively — keeps the password out of shell history
npx secretless-ai secret set SN_MYDEV01_PASSWORD

2. Aktualisieren Sie Ihre MCP-Konfiguration, um secretless-ai run als Wrapper zu verwenden. Das --only-Flag teilt mit, welche Geheimnisse injiziert werden sollen. SN_INSTANCE ist kein Geheimnis und bleibt im env-Block:

{
	"mcpServers": {
		"sn_mydev01": {
			"command": "npx",
			"args": ["-y", "secretless-ai", "run", "--only", "SN_MYDEV01_USERNAME,SN_MYDEV01_PASSWORD", "--", "npx", "-y", "sn-mcp-bridge"],
			"env": {
				"SN_INSTANCE": "https://mydev01.service-now.com"
			}
		}
	}
}

Für mehrere Instanzen wiederholen Sie das Muster – speichern Sie die Anmeldedaten jeder Instanz unter ihren präfixierten Namen und fügen Sie einen Servereintrag mit der entsprechenden --only-Liste hinzu:

{
	"mcpServers": {
		"sn_mydev01": {
			"command": "npx",
			"args": ["-y", "secretless-ai", "run", "--only", "SN_MYDEV01_USERNAME,SN_MYDEV01_PASSWORD", "--", "npx", "-y", "sn-mcp-bridge"],
			"env": {
				"SN_INSTANCE": "https://mydev01.service-now.com"
			}
		},
		"sn_myprod01": {
			"command": "npx",
			"args": ["-y", "secretless-ai", "run", "--only", "SN_MYPROD01_USERNAME,SN_MYPROD01_PASSWORD", "--", "npx", "-y", "sn-mcp-bridge"],
			"env": {
				"SN_INSTANCE": "https://myprod01.service-now.com"
			}
		}
	}
}

Das Konfigurationsformat für andere Editoren folgt demselben Muster, das unter Quick Start gezeigt wird — ersetzen Sie einfach command/args durch den secretless Wrapper.

Unterstützte Backends

Alternative: protect-mcp

Wenn sich Ihre MCP-Konfigurationen in globalen Konfigurationspfaden befinden (z.B. ~/.vscode/mcp.json, ~/.cursor/mcp.json), können Sie protect-mcp verwenden, um sie automatisch in einem Durchgang zu scannen und zu sichern:

npx secretless-ai protect-mcp --backend keychain

Sie können den Status überprüfen oder mit mcp-status und mcp-unprotect rückgängig machen:

npx secretless-ai mcp-status
npx secretless-ai mcp-unprotect

Einschränkung: protect-mcp, mcp-status und mcp-unprotect erkennen nur globale Konfigurationsdateien. Sie finden keine Konfigurationen auf Arbeitsbereichsebene wie .vscode/mcp.json, .mcp.json oder .codex/config.toml in Projektverzeichnissen. Verwenden Sie für Arbeitsbereichskonfigurationen den oben beschriebenen Ansatz secret set + run.

Weitere Informationen zu Secretless AI finden Sie in der vollständigen Dokumentation.

Voraussetzungen

• Node.js 18+ (für natives fetch)

• Eine ServiceNow-Instanz mit REST-API-Zugriff

• Entweder Basisauthentifizierungsdaten für die Instanz oder eine registrierte OAuth-Anwendung (siehe Authentication)

Lizenz

MIT