servicenow-mcp-ai — ServiceNow MCP Server

📖 Documentation site →

A Model Context Protocol server that lets an MCP client (VS Code, Claude Desktop, etc.) run commands against a ServiceNow instance through its REST APIs — Table, Aggregate, Attachment, Import Set, Batch and CMDB, plus the Service Catalog, Change Management and Knowledge plugin APIs. Credentials are kept in a local env file and can be updated at runtime through a tool.

Upgrading from 2.x? 3.0 has breaking defaults (plan tokens for destructive applies, protected system tables, a smaller default tool set). Run npx servicenow-mcp-ai migrate --write once: it carries your env file and MCP client config over and adds SN_COMPAT=2, which keeps every 2.x default you have not set. See the CHANGELOG → "Migration at a glance" for each change.

Upgrading from 1.x? v2.0 makes writes plan-by-default: create/update/delete and the other record-write tools return a non-mutating preview unless you pass apply: true (or set SN_WRITE_MODE=apply to restore the v1 "execute immediately" behaviour). See the CHANGELOG → 2.0.0 for the full migration note.

Contents: Quick demo · Features · Requirements · Setup · Configure credentials · Run / debug · Develop · Tools · Resources · Prompts · Project structure · Security notes · Project documentation · Support

Built and maintained in my own time — if it helps, a GitHub Sponsors tip keeps it going. Full Support options are near the end.

Quick demo

Three things the platform makes hard, one call each. Point your MCP client at an instance (Setup) and ask:

1. "Where is this field actually used?" — every script, business rule, client script, UI policy/action and ACL that touches it, as JSON or a Mermaid graph. The IDE-grade find usages ServiceNow has no button for:

// servicenow_where_used
{
  "kind": "field", // "table" | "field" | "script"
  "name": "u_cost_center",
  "mermaid": true, // also render a reference graph
}

2. "What runs when I save this record?" — the full automation chain in execution order (display → before → after → async business rules, then flows, workflows and notifications), each with its condition — a logical test that runs nothing:

// servicenow_trace_table_event
{
  "table": "incident",
  "operation": "update", // insert | update | delete | query
}

3. "What drifted between dev and prod?" — a Markdown diff of tables, columns, scripts (matched by sys_id then name, with a unified diff of every changed script) and plugins between two configured profiles — plus, on request, properties, choices, ACLs, notifications, flows, catalog items and roles — with a CI-friendly exit code so a pipeline can block a risky deploy:

servicenow-mcp-ai drift dev prod   # report on stdout; exit 1 on drift, 0 if clean

All three are read-only and work against any instance — including a free PDI — with the model and client of your choice.

Features

• Full Table API: query, read, create, update and delete records on any table, with encoded queries, field selection and pagination.
• Extra ServiceNow APIs: Aggregate (Stats), Attachment (list/upload/download/delete), Import Set, Batch (many REST calls in a single request), plus table/column metadata (sys_db_object, sys_dictionary).
• Process & plugin APIs: CMDB (class-aware CI CRUD + meta, relationship reads from cmdb_rel_ci, IRE identify-and-reconcile with an identify-only plan), Service Catalog (browse/order items), Change Management (typed creation + conflict detection) and Knowledge (article search). Plugin-scoped APIs report clearly when not active on the instance.
• Script intelligence: read and search the instance's own code (business rules, script includes, client scripts, UI policies/actions, scheduled jobs, transform/REST scripts, ACLs, Service Portal widgets, UI pages/scripts/macros, processors, email/fix/ validation scripts, script actions, data sources, REST message functions, transform maps/entries, catalog client scripts and dictionary calculations / defaults) and get a table's full automation picture — all read-only over the Table API. servicenow_search_code returns every matching line per artefact (up to 20, with a line of context either side) and, like servicenow_where_used, takes an optional application scope. servicenow_where_used also finds structural references — dictionary reference fields, list and form layouts, catalog variables, flow inputs and reports — in a separate structural section.
• Flow tracing & code checking (Phase 8): deterministically trace what a table operation runs (flows package — business rules, flows, workflows and notifications, in order, with a Mermaid flowchart), read Flow Designer flows and run history, explain Process Automation Designer playbooks (servicenow_explain_flow with kind: "playbook" — lanes as Mermaid subgraphs, activities, triggers, variants), and lint scripts against a local rule set with an aggregate code-health report (codecheck; domains: true adds the flow, Service Portal and legacy-workflow analysers). Run ATF tests via the CI/CD API (atf, opt-in, non-default — the run tools execute on the instance).
• Journal-based undo (revert): list the local write journal and revert one applied create/update/delete — with a drift check against later edits.
• Generic artifact reads (artifacts, opt-in): list and read any registered artifact type — UI policies with their actions, portal pages with their layout, flows, catalog items and more — with scope and SDK-managed status.
• Update-set awareness (updatesets, opt-in): list update sets, summarise one set per artefact, compare it with another profile or a snapshot — and bind applied Table writes to a named update set (update_set / SN_UPDATE_SET), restoring the user's current set afterwards.
• Operations and data health (ops, opt-in): bounded "why is it slow" reads of the system log, the scheduler queue, the outbound email queue and semaphores, plus servicenow_check_data_health — duplicate keys, orphaned and stale references for one table, from Aggregate API counts.
• Operations reads (opt-in): a record's change history from sys_audit and sys_journal_field (history — including the comments and work notes the Table API reads back empty), system properties with masked secrets and a journaled, revertible set (properties), and user / group / role lookups with memberships (directory). ATF runs can wait for their result (wait_seconds), and Import Set inserts report the transform run and maps.
• Self-documentation: a local Markdown knowledge base (read/write/search) plus deterministic Mermaid generators (ER diagrams from references, record-lifecycle flowcharts from business rules) so the server builds durable, reusable context.
• Prompts: ready-made workflows (incident triage, change impact analysis, document a table, diagnose a slow instance, safe write, drift review, schema impact, instance discovery) that orchestrate the tools; every plugin skill has a prompt twin for clients without the plugin.
• Tool packages: load only the tool groups you need via SN_TOOL_PACKAGES (default profile discovery; all enables everything).
• Basic or OAuth 2.0 authentication over HTTPS; the password/token is never echoed back.
• Least-privilege controls: table allow/deny lists and a global read-only mode.
• Resilience: per-request timeout, retry with backoff and Retry-After, SSRF guard, and a result-size guard.
• MCP tool annotations and resources, structured error payloads, and structured logging on stderr.
• Credentials in an env file (project, ~/.config, or SN_ENV_FILE), updatable at runtime via servicenow_set_credentials.

Requirements

• Node.js 22.12+ (enforced: engines + a runtime guard with a clear message; the project targets the version in .nvmrc).

Setup

From source (for development):

npm install
npm run build

Or run the published package directly, without cloning:

npx servicenow-mcp-ai

Install in your MCP client

Every client launches the same stdio command, npx -y servicenow-mcp-ai (Node.js 22.12+), under the server name servicenow. The one-click links and snippets below carry no credentials: keep them in the env file (~/.config/servicenow-mcp-ai/.env, see Configure credentials), run the one-time npx servicenow-mcp-ai login for OAuth, or ask the assistant to call servicenow_set_credentials once the server is connected. A real environment variable set in a client config overrides the env file, so only add an env block when you mean it — and never put SN_PASSWORD or other secrets into a client config you share or commit (see SECURITY.md).

Client	One line	Config file
VS Code (Copilot Chat)	Button above, or code --add-mcp (below) — or the ServiceNow MCP extension	.vscode/mcp.json (servers)
VS Code Insiders	Button above, or code-insiders --add-mcp (below)	.vscode/mcp.json (servers)
Claude Code	claude mcp add servicenow -- npx -y servicenow-mcp-ai, or the plugin	.mcp.json (mcpServers)
Claude Desktop	— (edit the config file)	claude_desktop_config.json (mcpServers)
Cursor	Button above, or the cursor:// deeplink (below)	~/.cursor/mcp.json or .cursor/mcp.json (mcpServers)
Windsurf	— (edit the config file)	~/.codeium/windsurf/mcp_config.json (mcpServers)
Cline	— (MCP Servers → Configure MCP Servers)	cline_mcp_settings.json (mcpServers)
Zed	— (edit settings)	settings.json (context_servers)
JetBrains AI Assistant	— (Settings → Tools → AI Assistant → Model Context Protocol)	JSON dialog (mcpServers)
Gemini CLI	— (edit settings)	~/.gemini/settings.json (mcpServers)
Codex CLI	codex mcp add servicenow -- npx -y servicenow-mcp-ai	~/.codex/config.toml ([mcp_servers.servicenow])

The zero-config route is the ServiceNow MCP extension from the Marketplace (code --install-extension ivanbbaev.servicenow-mcp-ai); it registers the server in Copilot Chat (agent mode) automatically, no mcp.json. Source: extension/.

Without the extension, add the server from a terminal (user profile):

code --add-mcp '{"name":"servicenow","command":"npx","args":["-y","servicenow-mcp-ai"]}'
code-insiders --add-mcp '{"name":"servicenow","command":"npx","args":["-y","servicenow-mcp-ai"]}'

The raw deeplinks behind the buttons (paste into a browser address bar):

vscode:mcp/install?%7B%22name%22%3A%22servicenow%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22servicenow-mcp-ai%22%5D%7D
vscode-insiders:mcp/install?%7B%22name%22%3A%22servicenow%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22servicenow-mcp-ai%22%5D%7D

Or a workspace file, .vscode/mcp.json:

{
  "servers": {
    "servicenow": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "servicenow-mcp-ai"]
    }
  }
}

Plugin (zero-config — installs the server wired up):

/plugin marketplace add IvanBBaev/servicenow-mcp-ai
/plugin install servicenow-mcp-ai

The plugin also ships eight workflow skills, two read-only subagents and three hooks — see Plugin skills.

CLI — --scope user makes it available in every project; --env sets a non-secret variable (the instance host) and leaves the secrets in the env file. A value set this way wins over the env file, so drop --env if you switch instances with servicenow_set_credentials:

claude mcp add servicenow --scope user --env SN_INSTANCE=your-instance.service-now.com -- npx -y servicenow-mcp-ai

claude_desktop_config.json — macOS ~/Library/Application Support/Claude/, Windows %APPDATA%\Claude\ (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "servicenow": {
      "command": "npx",
      "args": ["-y", "servicenow-mcp-ai"]
    }
  }
}

Restart Claude Desktop after saving.

Use the button above, or open the deeplink directly:

cursor://anysphere.cursor-deeplink/mcp/install?name=servicenow&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsInNlcnZpY2Vub3ctbWNwLWFpIl19

Or edit ~/.cursor/mcp.json (global) / .cursor/mcp.json (project) with the same mcpServers block as Claude Desktop.

All three take the Claude Desktop mcpServers block unchanged:

• Windsurf — ~/.codeium/windsurf/mcp_config.json (Cascade → MCP servers → View raw config), then refresh the server list.
• Cline — MCP Servers icon → Configure MCP Servers opens cline_mcp_settings.json.
• JetBrains AI Assistant — Settings → Tools → AI Assistant → Model Context Protocol (MCP) → Add → As JSON, paste the block.

{
  "mcpServers": {
    "servicenow": {
      "command": "npx",
      "args": ["-y", "servicenow-mcp-ai"]
    }
  }
}

In Zed's settings.json (Zed → Settings → Open Settings):

{
  "context_servers": {
    "servicenow": {
      "source": "custom",
      "command": "npx",
      "args": ["-y", "servicenow-mcp-ai"],
      "env": {}
    }
  }
}

~/.gemini/settings.json (user) or .gemini/settings.json (project):

{
  "mcpServers": {
    "servicenow": {
      "command": "npx",
      "args": ["-y", "servicenow-mcp-ai"]
    }
  }
}

Check it with /mcp inside a Gemini CLI session.

codex mcp add servicenow --env SN_INSTANCE=your-instance.service-now.com -- npx -y servicenow-mcp-ai

Or ~/.codex/config.toml:

[mcp_servers.servicenow]
command = "npx"
args = ["-y", "servicenow-mcp-ai"]
# Optional, non-secret only — secrets stay in ~/.config/servicenow-mcp-ai/.env:
# env = { SN_INSTANCE = "your-instance.service-now.com" }

Prefer a global install (npm install -g servicenow-mcp-ai)? Replace "command": "npx", "args": ["-y", "servicenow-mcp-ai"] with "command": "servicenow-mcp-ai" in any snippet. The MCP Inspector works the same way: npx @modelcontextprotocol/inspector npx -y servicenow-mcp-ai.

The one-click links are generated from package.json by scripts/install-links.mjs (node scripts/install-links.mjs prints them); test/install-links.test.js fails if this README or the docs site drift from the generated strings.

Install via MCP bundle (.mcpb)

An MCP bundle is one .mcpb file with the server and its dependencies; Claude Desktop (or any MCPB host) installs it in one click, with no npm / npx. Its form asks for the connection keys (only SN_INSTANCE is required) and SN_TOOL_PACKAGES; secrets are marked sensitive (kept in the OS keychain). An empty field falls back to the env file. Not published yet (O-22) — build it with npm run mcpb:pack (dist/mcpb/; -- --validate runs the official validator).

Docker

The repository ships a multi-stage Dockerfile (distroless Node 22 runtime, non-root uid 65532). The image contains exactly what npm pack publishes plus production dependencies, and starts the HTTP transport on 0.0.0.0:3000 by default. No image is published to a registry yet — build it locally:

docker build -t servicenow-mcp-ai .

# Secrets as files (Docker / Kubernetes secrets), mounted read-only
mkdir -p secrets && printf '%s' 'your-password' > secrets/sn_password
openssl rand -hex 32 > secrets/sn_http_token

docker run --rm -p 127.0.0.1:3000:3000 \
  -e SN_INSTANCE=your-instance.service-now.com -e SN_USER=your.user \
  -e SN_PASSWORD_FILE=/run/secrets/sn_password \
  -e SN_HTTP_TOKEN_FILE=/run/secrets/sn_http_token \
  -v "$PWD/secrets:/run/secrets:ro" -v sn-data:/data \
  servicenow-mcp-ai

• SN_HTTP_TOKEN is required for any non-loopback bind. The image binds 0.0.0.0 so the published port works; without a token (or OAuth) the server refuses to start (3.0, B6). SN_HTTP_REQUIRE_TOKEN=0 lets it start with a warning, and then every client that reaches the port drives your instance with the configured credentials. Clients send Authorization: Bearer <token>; terminate TLS in front of the container.
• OAuth instead of a shared token (N-17): set SN_HTTP_OAUTH_ISSUER (your OIDC provider) and SN_HTTP_OAUTH_RESOURCE (this server's public URL, e.g. https://mcp.example.com/mcp). Clients discover the issuer from /.well-known/oauth-protected-resource and send its JWT access tokens; the token must name the resource as its audience. Optional: SN_HTTP_OAUTH_SCOPES, SN_HTTP_OAUTH_AUDIENCE, SN_HTTP_OAUTH_JWKS_URI. For an issuer that hands out opaque tokens, set SN_HTTP_OAUTH_INTROSPECTION_URI plus its client id and secret (RFC 7662). By default the instance is still called with the configured service account.
• Per-user ServiceNow access (N-17 phase 2): add SN_HTTP_OAUTH_USER_TOKENS=true, a 32-byte SN_HTTP_OAUTH_TOKEN_KEY (base64 or hex, e.g. openssl rand -base64 32) and an OAuth client on the instance (SN_OAUTH_CLIENT_ID / SN_OAUTH_CLIENT_SECRET, refresh tokens enabled) whose redirect URL is /oauth/servicenow/callback on the SN_HTTP_OAUTH_RESOURCE origin. The first call from a user returns a link to the instance's sign-in page (URL elicitation; a 2025 session gets -32042, a client without URL elicitation and a background task get an error carrying the link). After the user signs in, the server checks that the account's sys_user field matches the token's claim (SN_HTTP_OAUTH_USER_MATCH, default email=email), keeps the refresh token AES-256-GCM encrypted in SN_HTTP_OAUTH_TOKEN_STORE, and from then on calls the instance as that user, so ServiceNow ACLs apply per user. A user drops their own links with DELETE /oauth/servicenow/link (their bearer token; answers { unlinked, revoked }); the refresh tokens are also revoked on the instance, best effort. Replicas behind one SN_HTTP_OAUTH_RESOURCE can each complete a link when they share SN_HTTP_OAUTH_TOKEN_KEY and the store. Limit: requests authorized with SN_HTTP_TOKEN still use the shared credential.
• /data holds the docs directory (SN_DOCS_DIR=/data/docs) and the env file (SN_ENV_FILE=/data/.env); mount a volume there to keep them.
• Every <KEY>_FILE secret source is described in Secrets from files.
• For an MCP client that spawns the container over stdio, pass -i -e SN_TRANSPORT=stdio (docker run --rm -i -e SN_TRANSPORT=stdio -e SN_INSTANCE=… servicenow-mcp-ai).
• The HEALTHCHECK is a TCP liveness probe. GET /healthz (liveness) and GET /readyz (credentials configured) answer without the token for orchestrator probes; GET /readyz?probe=1 also calls the instance and sits behind the token, like every MCP route. Set SN_HTTP_ALLOWED_HOSTS to the name clients use so the Host header is checked on a 0.0.0.0 bind.
• smithery.yaml describes the same image for Smithery (stdio, config keys mapped to the SN_* settings).

HTTP transport: sessions, probes and shutdown

With SN_TRANSPORT=http every MCP session (one initialize) gets its own server: