Servicenow Mcp Ai

Quick demo

Three things the platform makes hard, one call each. Point your MCP client at an instance ([Setup](#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 (by SHA-256) and plugins between two configured profiles, 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 via IRE),

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 get a table's full automation picture — all read-only over the Table API.

• 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, and lint scripts against a local rule set with an aggregate code-health report (codecheck). Run ATF tests via the CI/CD API (atf, opt-in, non-default — the run tools execute on the instance).

• 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) 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 20+ (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

Register it with an MCP client (Claude Desktop, VS Code Chat, the Inspector…) by pointing the server command at npx:

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

Claude Code plugin (zero-config — installs the server wired up):

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

VS Code — install 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 manual mcp.json. Source: [extension/](extension/).

Credentials are read from ~/.config/servicenow-mcp-ai/.env (or real environment variables) — see below.

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](#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](#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.

1. 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

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.

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.

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](.env.example).

Supported authentication methods

Every inbound REST auth method ServiceNow offers is covered:

| Method | SN_AUTH | Set | Notes | | ------ | --------- | --- | ----- | | Basic | basic | SN_USER / SN_PASSWORD | Default. | | OAuth 2.1 — Authorization Code + PKCE | oauth | npx servicenow-mcp-ai login | Recommended. Interactive, stores a refresh token. | | OAuth — Client Credentials | oauth | SN_OAUTH_GRANT=client_credentials | Service-to-service. | | OAuth — Refresh Token | oauth | SN_OAUTH_GRANT=refresh_token + SN_OAUTH_REFRESH_TOKEN | Set by login. | | OAuth — JWT Bearer | oauth | SN_OAUTH_GRANT=jwt_bearer + SN_OAUTH_JWT_KEY | RS256 assertion; no password. | | OAuth — Password (ROPC) | oauth | SN_OAUTH_GRANT=password | Deprecated. | | API Key | apikey | SN_API_KEY | x-sn-apikey header. | | Bearer token | token | SN_BEARER_TOKEN | Pre-obtained token, used verbatim. | | Mutual TLS (client cert) | none (or layered) | SN_TLS_CLIENT_CERT / _KEY | Cert maps to a user; needs optional undici. |

Environment variables

All settings are read from .env (or the real process environment, which takes precedence). Only the first three are required; the rest are optional tuning knobs. See [.env.example](.env.example) for a template.

| Variable | Required | Default | Description | | ------------------------ | :------: | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | SN_INSTANCE | yes | — | Instance name, host, or https:// URL (dev12345, dev12345.service-now.com). | | SN_USER | yes | — | ServiceNow username for Basic auth. | | SN_PASSWORD | yes | — | ServiceNow password. Never logged or returned by any tool. | | SN_TIMEOUT_MS | no | 30000 | Per-request timeout in milliseconds. | | SN_MAX_RETRIES | no | 2 | Retries for transient failures (429/5xx, network errors). Non-idempotent writes are only retried on connect errors. | | SN_MAX_RECORDS | no | 10000 | Hard cap on records returned by a fetchAll query. | | SN_MAX_RESULT_CHARS | no | 100000 | Character budget for a query result before it is truncated for the client. | | SN_ALLOWED_HOSTS | no | — | Comma-separated allow-list of permitted hosts (for custom or sovereign-cloud domains). When set, only matching hosts are contacted. When unset, only *.service-now.com instances are allowed and internal/loopback hosts are blocked (SSRF guard). | | SN_AUTH | no | auto | Auth method: basic, oauth, apikey, token or none (cert-only mTLS). Auto-detected from the keys present (API key → bearer → OAuth → Basic). | | SN_API_KEY | no | — | ServiceNow Inbound API Key, sent as the x-sn-apikey header (enables apikey mode). | | SN_BEARER_TOKEN | no | — | A pre-obtained bearer token, sent verbatim as Authorization: Bearer … (enables token mode). | | SN_OAUTH_CLIENT_ID | no | — | OAuth client id (its presence enables OAuth). | | SN_OAUTH_CLIENT_SECRET | no | — | OAuth client secret. | | SN_OAUTH_GRANT | no | password | OAuth grant: password (deprecated — ROPC), client_credentials, refresh_token or `jw

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: IvanBBaev
• Source: IvanBBaev/servicenow-mcp-ai
• License: MIT
• Homepage: https://ivanbbaev.github.io/servicenow-mcp-ai/

Install and usage instructions live in the source repository linked above.