io.github.IvanBBaev/servicenow-mcp-ai

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 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 — and, not yet verified on a live instance, 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) that orchestrate the tools.
• Tool packages: load only the tool groups you need via SN_TOOL_PACKAGES (default profile core; 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).

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"]}'

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

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

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

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

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

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

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

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

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

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

[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 every client that reaches the port drives your instance with the configured credentials (the server logs a warning). Clients send Authorization: Bearer <token>; terminate TLS in front of the container.
• /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:

• Per-session state. Enabled packages, the MCP logging level, list-changed notifications, plan tokens, tasks and write caps belong to the session. Connection pools, OAuth tokens and the schema cache are shared and keyed by profile + host.
• servicenow_use_instance is session-scoped over HTTP. It switches the profile of the calling session only; other sessions keep theirs and nothing is written. Pass persist: true to also write SN_ACTIVE_PROFILE to the env file (journaled) — that changes the default for sessions that have not switched. Over stdio the switch is persisted by default, as before (persist: false makes it process-only).
• Lifetime. A session ends on DELETE or after SN_HTTP_SESSION_TTL_SEC idle (default 30 min); a request with an ended session id gets 404 and the client re-initializes. At most SN_HTTP_MAX_SESSIONS (64) are open at once.
• DNS-rebinding protection. The Host header must match SN_HTTP_ALLOWED_HOSTS (default: the loopback names on a loopback bind) and a browser Origin must match SN_HTTP_ALLOWED_ORIGINS (default: loopback origins); otherwise 403.
• Probes. GET /healthz → 200 {"status":"ok"} while serving. GET /readyz → 200 when credentials are configured, 503 otherwise. Both answer without the token. GET /readyz?probe=1 (behind the token) also reads one sys_user row and returns 503 when the instance is unreachable; the result is cached for 5 s.
• Shutdown. On SIGTERM / SIGINT the listener stops accepting connections, new requests get 503, in-flight tool calls get up to 5 s to finish, then every session is closed and the process exits 0.
• Keep-alive. Open SSE streams get a comment every SN_HTTP_KEEPALIVE_MS (25 s).

Quickstart

The fastest path is three lines of Basic auth — set these (in the env file or the real environment) and you are connected:

SN_INSTANCE=dev12345.service-now.com
SN_USER=your.username
SN_PASSWORD=your-password

Everything else is optional tuning; see the full Environment variables reference for the rest.

Past a quick try, prefer OAuth over a stored password. For anything shared or long-lived, run the one-time npx servicenow-mcp-ai login instead — it stores a refresh token, not your password. See Configure credentials → OAuth 2.1.

Verify your setup

Once the three variables are set, confirm the connection before you start:

1. Run the servicenow_test_connection tool — it reads one sys_user record and reports ok, HTTP status and latency.
2. Run servicenow_check_capabilities — it previews which admin-restricted sys_* tables the connected user can actually read.

Or do both from the shell in one shot:

npx servicenow-mcp-ai doctor   # checks credentials, reachability and capabilities

Prefer to be asked? npx servicenow-mcp-ai init prompts for the instance, the auth method and the credentials, writes the env file and runs doctor — see Command-line interface.

Configure credentials

Credentials live in .env at the project root (git-ignored):

SN_INSTANCE=your-instance.service-now.com
SN_USER=your.username@example.com
SN_PASSWORD=your-password

SN_INSTANCE accepts dev12345, dev12345.service-now.com or a full https:// URL.

You can also set or change them at runtime by calling the servicenow_set_credentials tool — the new values are written straight back to the env file. Moving a configured profile to a different instance requires user and password in the same call (the stored secrets are never sent to another host), and the change must be confirmed by the client — clients without elicitation support are refused unless SN_ALLOW_UNCONFIRMED_CREDENTIAL_CHANGE=1 is set.

The tool also sets the auth method (auth), the OAuth client id (oauth_client_id) and grant (oauth_grant). Secrets — the API key and the OAuth client secret — are never tool arguments: list them in request_secrets and the server asks for them through an elicitation prompt, so they never appear in a logged tool call, the result or the write journal. A client without elicitation support is refused (the opt-out above does not apply to secrets); set those keys in the env file instead. The instance-change rule follows the resulting auth method: an API-key profile needs a new API key, an OAuth client_credentials profile a new client secret, the OAuth password grant user, password and client secret, Basic / none user and password; bearer-token, refresh_token and jwt_bearer profiles cannot be moved with this tool.

servicenow_get_status (authWarnings), servicenow_list_instances and doctor evaluate each profile against its own auth method — an API-key profile needs no password — and report the method, the OAuth grant, the refresh-token state and the write mode, never a secret value. When the refresh-token grant returns a rotated refresh token, it is written back to the env key it was read from; if the env file cannot be written, the new token is kept in memory (lost on restart) and a warning is logged and shown by get_status / doctor. Values the server writes keep Windows paths literal (backslashes are single-quoted) and a CRLF env file stays CRLF. On Windows the env file inherits its folder's ACL — restrict it yourself (for example icacls .env /inheritance:r /grant:r "%USERNAME%:F"); the server only warns, it never runs icacls.

The env file is resolved in this order: SN_ENV_FILE, then ~/.config/servicenow-mcp-ai/.env (XDG) if present, then the project-root .env. A global/npx install therefore writes to your user config rather than into node_modules. Real environment variables always take precedence over the file.

First run: the model configures itself

At initialize the server sends instructions built from the live configuration: the enabled packages and tool count, the write mode, the active profile and, when nothing is configured, what is missing and how to fix it. Until then every instance tool fails with code: "NOT_CONFIGURED" and a hint naming servicenow_set_credentials. A first session with an empty env file looks like this (abridged):

instructions  Credentials: NOT configured (missing instance, user, password). Instance tools
              fail with code NOT_CONFIGURED until fixed. To configure: ask the user for
              the instance and credentials, call servicenow_set_credentials, then
              servicenow_test_connection. Never guess or echo a password.
user          How many open P1 incidents do we have?
model         Which instance, user and password should I connect with?
user          dev12345, admin, ••••••
tool call     servicenow_set_credentials { instance: "dev12345", user: "admin", password: … }
tool result   { message: "Credentials saved", profile: "default", configured: true, password: "***" }
tool call     servicenow_test_connection {}
tool result   { ok: true, … }
tool call     servicenow_aggregate { table: "incident", query: "active=true^priority=1" }
model         There are 7 open P1 incidents.

servicenow_get_status then shows the live state: server version, uptime and transport, policy.summary, limits, redaction, the docs directory, write counters, the profile source and profileDetails (per-profile auth mode, write mode and missing keys) — never a secret value.

OAuth 2.1 (Authorization Code + PKCE) — recommended

Register an Authorization Code OAuth API endpoint in ServiceNow with a loopback redirect URL (e.g. http://localhost:53682/callback), set SN_OAUTH_CLIENT_ID (and SN_OAUTH_CLIENT_SECRET for a confidential client), then run the one-time interactive login:

npx servicenow-mcp-ai login

It opens the browser, you approve, and the obtained refresh token is stored in your env file. The server then runs non-interactively (refresh_token grant) — no password is ever stored. PKCE (S256) is always used.

The OAuth 2.0 password grant (ROPC) is deprecated in OAuth 2.1 and disabled on many instances; prefer login. client_credentials and refresh_token grants remain supported for service accounts. See .env.example.

Supported authentication methods

Every inbound REST auth method ServiceNow offers is covered:

Environment variables

All settings are read from the env file (SN_ENV_FILE, else ~/.config/servicenow-mcp-ai/.env) or the real process environment, which takes precedence. Only the first three are required; the rest are optional tuning knobs. See .env.example for a template. Every value is validated at startup: an invalid one is logged as a warning and the setting keeps its default, or — with SN_STRICT_SETTINGS=1 — stops the server with an error.

These tables are generated from the settings manifest (src/core/settings-manifest.ts) — edit the manifest, then run npm run docs:env.

Connection and authentication

The instance and its credentials. Only SN_INSTANCE is always required; the auth method is auto-detected from the keys present (API key -> bearer token -> OAuth -> Basic) unless SN_AUTH names it.

Secrets from files

Container secrets (D-5): FILE=/path loads from that file at startup (one trailing newline is trimmed). Setting both and FILE is a startup error; so is an unreadable or empty file. A value loaded this way is never written back to the env file. Per profile: SN_PROFILE_FILE for the ServiceNow secrets.

Profiles and the env file

The bare SN_INSTANCE / SN_USER / SN_PASSWORD keys are the 'default' profile. More instances live under SN_PROFILE__* keys; switch with SN_ACTIVE_PROFILE or the servicenow_use_instance tool.

Network, TLS and resilience

Timeouts, retries, the host allow-list, the outbound proxy, mutual TLS and the per-host queue and circuit breaker. They govern every REST client of the server. The proxy and mutual TLS need the optional undici package.

Tool packages

Which tools are registered. The admin tools (set_credentials, get_status, use_instance) are always on.

Access policy and write safety

Least-privilege table policy, plan-and-apply writes, destructive-write confirmation, per-session caps, prod profiles, update-set binding and the upload / email / SDK-managed-scope guards.