snow-mcp-gateway

Built by @AIbyTusharM — subscribe for more such tools, learning and walkthroughs.

A local gateway that turns ServiceNow REST APIs into MCP (Model Context Protocol) tools, so they can be used by Claude Desktop, Claude Code, or any MCP-compatible client.

You point the gateway at a ServiceNow instance, declare tools in a web UI (each tool wraps a Table API or Scripted REST endpoint), and the gateway exposes them as MCP servers over Streamable HTTP. Each MCP server runs on its own port and can be hot-edited without restarting clients.

Architecture

Claude Desktop ──stdio──▶ mcp-remote ──HTTP──▶ snow-mcp-gateway ──REST──▶ ServiceNow
Claude Code  ──────────────HTTP────────────▶       │
                                                   ├─ Management UI (port 3001)
                                                   ├─ incident-mcp        (port 7801)
                                                   ├─ change-ops          (port 7820)
                                                   ├─ cmdb-server         (port 7850)
                                                   ├─ business-rule-mcp   (port 8110)
                                                   ├─ script-include-mcp  (port 8120)
                                                   └─ client-script-mcp   (port 8140)

• Management process serves the web UI on MANAGEMENT_PORT (default 3001) and a REST API at /api.

• Each MCP server is its own Express app on its own port, mounting POST/GET/DELETE /mcp via the official MCP TypeScript SDK's StreamableHTTPServerTransport.

• Tools are persisted to data/store.json (checked in — see Bundled MCP servers) and read live on every tools/list and tools/call, so adding or editing a tool takes effect immediately without restarting clients.

Related MCP server: servicenow-mcp-server

Quick start

# 1. Install dependencies
npm install

# 2. Create your local env file
cp .env.example .env
# then edit .env with your ServiceNow instance + credentials

# 3. Run the gateway
npm run dev          # tsx watch — hot reload on file changes
# or
npm run build && npm start

Open the management UI at http://localhost:3001. The repo ships with six MCP servers pre-configured (see Bundled MCP servers) — they auto-start on launch. From the UI you can:

1. Click Connect Instance and paste your ServiceNow URL, username, and password. The gateway tests the connection before saving.

2. Browse the pre-bundled servers in the sidebar — click any tool to edit, or click Add Tool to extend a server.

3. Click Create MCP Server to spin up a new one on a fresh port.

4. Click Config snippet on any server to get the JSON to paste into Claude Desktop / Claude Code.

Bundled MCP servers

These ship in data/store.json and start automatically. Tool definitions are live-editable from the UI.

Convention across CRUD tools:

• create_* — POST to the table collection URL; required fields go in the body.

• list_* — GET; takes sysparm_query, sysparm_limit, sysparm_fields. No script parameter — pass sysparm_fields='sys_id,name,description' for a lean list view.

• get_* — GET to /{table}/{sys_id}; returns the full record including script body.

• update_* — PATCH to /{table}/{sys_id}; pass only the fields you want to change.

ServiceNow's boolean fields (active, action_insert, etc.) are declared as string so they're sent as "true"/"false" — the Table API rejects raw JSON booleans for these columns.

Wiring into Claude Desktop

The gateway speaks Streamable HTTP. Claude Desktop speaks stdio. Bridge them with mcp-remote.

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "incident-mcp":       { "command": "npx", "args": ["mcp-remote", "http://localhost:7801/mcp"] },
    "change-ops":         { "command": "npx", "args": ["mcp-remote", "http://localhost:7820/mcp"] },
    "cmdb-server":        { "command": "npx", "args": ["mcp-remote", "http://localhost:7850/mcp"] },
    "business-rule-mcp":  { "command": "npx", "args": ["mcp-remote", "http://localhost:8110/mcp"] },
    "script-include-mcp": { "command": "npx", "args": ["mcp-remote", "http://localhost:8120/mcp"] },
    "client-script-mcp":  { "command": "npx", "args": ["mcp-remote", "http://localhost:8140/mcp"] }
  }
}

Restart Claude Desktop — the tools appear as native MCP tools.

The Config snippet button in the UI generates the per-server JSON for you with the correct port.

Wiring into Claude Code

Claude Code speaks Streamable HTTP natively — no mcp-remote wrapper needed.

CLI (one server at a time):

claude mcp add --transport http incident-mcp       http://localhost:7801/mcp
claude mcp add --transport http change-ops         http://localhost:7820/mcp
claude mcp add --transport http cmdb-server        http://localhost:7850/mcp
claude mcp add --transport http business-rule-mcp  http://localhost:8110/mcp
claude mcp add --transport http script-include-mcp http://localhost:8120/mcp
claude mcp add --transport http client-script-mcp  http://localhost:8140/mcp

Add --scope user to make them available across all projects.

Or drop a .mcp.json in your project root:

{
  "mcpServers": {
    "incident-mcp":       { "type": "http", "url": "http://localhost:7801/mcp" },
    "change-ops":         { "type": "http", "url": "http://localhost:7820/mcp" },
    "cmdb-server":        { "type": "http", "url": "http://localhost:7850/mcp" },
    "business-rule-mcp":  { "type": "http", "url": "http://localhost:8110/mcp" },
    "script-include-mcp": { "type": "http", "url": "http://localhost:8120/mcp" },
    "client-script-mcp":  { "type": "http", "url": "http://localhost:8140/mcp" }
  }
}

Run claude mcp list to verify, or /mcp inside an interactive session for live status.

Environment variables

Credentials can also be set/updated live via the UI; the running process picks them up immediately.

Project layout

src/
  index.ts          # bootstraps management API + auto-starts saved MCP servers
  routes.ts         # REST API for instance/servers/tools (under /api)
  mcp-manager.ts    # tracks running MCPInstance per server
  mcp-instance.ts   # Express + StreamableHTTPServerTransport per MCP server
  servicenow.ts     # REST client + tool dispatcher (Table API / Scripted REST)
  storage.ts        # JSON file persistence
  types.ts          # shared types
public/
  index.html        # single-file management UI
data/
  store.json        # persisted server + tool definitions (checked in)

Scripts

Notes

• Each MCP session gets its own SDK Server instance, because the SDK's Protocol class allows only one transport attachment per Server. Handlers read live from storage, so tool edits propagate to all sessions immediately.

• data/store.json is checked in so the bundled server + tool catalog ships with the repo. Your .env (with the password) is gitignored.

• Authentication to ServiceNow is HTTP Basic auth using the credentials you configure. Use a least-privilege service account, not a personal admin login, for any non-toy use.

Stay in the loop

If this was useful, follow AI by Tushar M on YouTube — subscribe for more such tools, learning and walkthroughs.