Drive ServiceNow from your AI assistant.

Three things the platform makes hard.

One call each — all read-only, against any instance (a free PDI included). The IDE-grade answers ServiceNow has no button for.

{ "kind": "field", "name": "u_cost_center", "mermaid": true }

{ "table": "incident", "operation": "update" }

servicenow-mcp-ai drift dev prod

What is this, exactly?

The Model Context Protocol (MCP) is an open standard that lets an AI assistant call external tools and read external resources. This project is an MCP server for ServiceNow: you register it with your MCP client once, and from then on the assistant can run real actions against your instance — query a table, create a change, inspect a business rule, compare two environments — instead of just talking about them.

Capabilities

Breadth of the platform, plus three things a generic CRUD connector doesn't give you.

Connected in under a minute.

Install once, point it at your instance, and add it to any MCP client. You need Node.js 20+ and a ServiceNow instance you can reach (a free Personal Developer Instance works great).

npm install -g servicenow-mcp-ai

export SN_INSTANCE=dev12345.service-now.com
export SN_USER=admin
export SN_PASSWORD=••••••

servicenow_test_connection

{
  "mcpServers": {
    "servicenow": {
      "command": "servicenow-mcp-ai"
    }
  }
}

SN_INSTANCE accepts dev12345, dev12345.service-now.com or a full https:// URL. Credentials can also live in a .env file (~/.config/servicenow-mcp-ai/.env or the project root) and be rotated at runtime via servicenow_set_credentials. Step 3 isn't a shell command — it's the servicenow_test_connection tool; ask your assistant to call it once the server is wired up.

Don't want a global install? Use "command": "npx", "args": ["-y", "servicenow-mcp-ai"] instead. On the Claude Code CLI it's a one-liner: claude mcp add servicenow -- npx -y servicenow-mcp-ai.

Talk to your assistant

That's it. Try something like:

The assistant calls servicenow_query_table with the right encoded query and returns the rows.

Credentials & where they live

The env file is resolved in this order:

1. SN_ENV_FILE — an explicit path, if set.
2. ~/.config/servicenow-mcp-ai/.env (XDG) — if it exists. A global / npx install writes here, not into node_modules.
3. The project-root .env (local development).

Real environment variables always win over the file. The file is written owner-only (0600) because it holds a plaintext password, and it is git-ignored — never commit real credentials.

Authentication

Basic auth works out of the box from the three required variables. For OAuth the recommended path is OAuth 2.1 — Authorization Code + PKCE via a one-time interactive login (no password is ever stored):

# 1) Register an "Authorization Code" OAuth endpoint in ServiceNow with a
#    loopback redirect, e.g. http://localhost:53682/callback
# 2) Set the client id (and secret for a confidential client):
SN_OAUTH_CLIENT_ID=your-client-id
SN_OAUTH_CLIENT_SECRET=your-client-secret
# 3) Log in once — opens the browser, captures the redirect, stores a refresh token:
npx servicenow-mcp-ai login

PKCE (S256) is always used, the loopback listener captures the redirect automatically, and the obtained refresh token is persisted — the server then runs non-interactively (refresh_token grant). The OAuth 2.0 password grant (ROPC) is deprecated and disabled on many instances; client_credentials and refresh_token remain available for service accounts.

Tokens are cached per host until just before expiry and are dropped automatically on a credential change or a server-side 401 (one transparent re-auth, then a real error). With named profiles you can even mix modes — prod on OAuth, dev on Basic — via the SN_PROFILE_<NAME>_AUTH / _OAUTH_* keys.

Every method ServiceNow supports

Multiple instances (dev + prod)

Define a profile per environment. A great default is a read-only prod and a full-access dev in one server:

# dev — full access (the default profile)
SN_PROFILE_DEV_INSTANCE=dev12345.service-now.com
SN_PROFILE_DEV_USER=admin
SN_PROFILE_DEV_PASSWORD=••••••

# prod — read-only
SN_PROFILE_PROD_INSTANCE=acme.service-now.com
SN_PROFILE_PROD_USER=svc.readonly
SN_PROFILE_PROD_PASSWORD=••••••
SN_PROFILE_PROD_READONLY=true

SN_ACTIVE_PROFILE=dev

Switch the active one with servicenow_use_instance, or target a single call by passing the automatic instance argument — every tool accepts it.

Command-line interface

The published servicenow-mcp-ai binary — run it directly or via npx servicenow-mcp-ai — has three invocations. All connection settings come from environment variables (see Environment variables); only drift takes positional arguments.

login — interactive OAuth

Operates on the active profile (SN_ACTIVE_PROFILE, default default) and reads, for that profile:

• SN_INSTANCE — required; the target instance.
• SN_OAUTH_CLIENT_ID — required; client id of an Authorization Code OAuth API endpoint.
• SN_OAUTH_CLIENT_SECRET — optional; for a confidential client.
• SN_OAUTH_REDIRECT_URI — optional; loopback URL, default http://localhost:53682/callback. Must match the redirect registered on the endpoint.
• SN_OAUTH_SCOPE — optional; requested OAuth scope.

On success it writes SN_AUTH=oauth, SN_OAUTH_GRANT=refresh_token and SN_OAUTH_REFRESH_TOKEN back to the env file (profile-prefixed when the profile is not default). The authorization URL is printed on stderr in case the browser does not open automatically.

npx servicenow-mcp-ai login

drift — CI drift gate (DF-3)

Takes two positional profile names; each must resolve to a configured profile (SN_PROFILE_<NAME>_*, or the bare SN_INSTANCE / SN_USER / SN_PASSWORD keys for default). The Markdown report goes to stdout (capture it as a CI artifact); a one-line drift summary goes to stderr — so a pipeline can block a deploy on configuration drift.

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

Environment variables

Only the first three are required; the rest are optional tuning knobs. See .env.example for a template.

* required.

Tool packages

Tools are grouped into packages so you expose only what a given client needs — fewer tools keep the model focused. Set SN_TOOL_PACKAGES to a comma/space-separated list of profiles or package names:

• core (default) — table, schema, aggregate, attachment.
• all — every package.
• Individual: table, schema, aggregate, attachment, importset, batch, catalog, change, knowledge, cmdb, scripts, flows, codecheck, docs, instance, email, atf.

# Only table + batch tools (the admin tools are always on)
SN_TOOL_PACKAGES=table,batch

The admin tools are always registered regardless of packages. Unknown names are ignored, and servicenow_get_status reports the resolved enabledPackages.

Tools reference

67 tools across 18 packages. read tools never mutate the instance; write tools respect the read-only and policy guards. Click any tool to expand its full parameter list — name, type, whether it is required and any allowed values.

Expand all Collapse all

No tools match that search.

table — Record CRUD over the Table API. (5 tools)

schema — Table & column metadata, including the inherited super_class chain. (2 tools)

aggregate — Server-side statistics (count / avg / min / max / sum) via the Stats API. (1 tool)

attachment — File attachments — list, read, download, upload and delete. (5 tools)

importset — Import Set staging inserts and their transform outcome. (2 tools)

batch — Several REST sub-requests in a single round-trip; policy is enforced per sub-request. (1 tool)

catalog — Service Catalog — browse catalogs, categories and items, then order. (5 tools)

change — Change Management — typed create (normal / standard / emergency), conflicts, update. (5 tools)

knowledge — Knowledge Base — relevance search and article retrieval. (3 tools)

cmdb — Class-aware configuration items through Identification & Reconciliation (IRE). (5 tools)

scripts — Read-only code intelligence over server-side script artefacts. (5 tools)

flows — Flow & automation intelligence (read-only) — event tracing, Flow Designer, run history. (4 tools)

codecheck — Local static analysis of instance scripts — no code is executed on the instance. (3 tools)

docs — Local Markdown self-documentation store and Mermaid diagram generators. (6 tools)

instance — Cross-instance structural snapshots and comparison. (2 tools)

email — Email — send and read. (2 tools)

atf — Automated Test Framework via the CI/CD API (opt-in, non-default — runs on the instance). (5 tools)

admin — Always-on connection, profile and status tools. (6 tools)

Use cases

What you'd actually ask your assistant to do. Each example is plain English — the server maps it to the right tools.

How it compares

ServiceNow now ships its own MCP Server Console — a governed, on-instance service for production AI agents. This project is a different tool for a different job: an external, self-run server for developers and consultants who need to understand and safely change an instance — any instance, with the model and client they choose.

Resources & prompts

MCP resources

Read-only metadata is also exposed as resources, so clients can attach it declaratively instead of calling a tool.

Prompts

Security & governance

An AI with write access to ServiceNow is high-stakes by definition. The server is built to keep that safe and auditable.

Full details — including the reporting channel — are in SECURITY.md.

Architecture

A small, layered TypeScript codebase with one-way dependencies (enforced at lint time), so each concern stays testable in isolation. Each layer may use only the layers beneath it:

Tools are data: a declarative manifest drives MCP registration, the generated docs and the contract snapshot tests, so adding a package touches exactly one list. A single tool call then flows through the same guards every time:

Tools are data: a declarative manifest drives MCP registration, the generated docs and the contract snapshot tests, so adding a package touches exactly one list. Quality is enforced by a single gate — npm run check (build, type-checked lint, format, coverage-gated tests, prod audit) — and a CI matrix across Node 20/22/24 + macOS. See ARCHITECTURE.md for the diagrams and ADRs.

Troubleshooting

Errors come back structured (with an HTTP status), so your assistant can usually explain them — but here are the common ones and their fix.

FAQ

How is this different from ServiceNow's own MCP Server?

ServiceNow's MCP Server Console is a governed, on-instance service for production agents (paid Now Assist SKU, metered). This is an external, self-run server for developers and consultants: it works against any instance — incl. a free PDI — with the model and client you choose, at no licence cost, and adds code intelligence and cross-instance diffing the platform service doesn't. See How it compares.

Does the AI run code on my instance?

No arbitrary code execution. There is no background-script evaluation; everything goes through documented REST APIs, and writes obey the policy and read-only guards. The one exception is the opt-in, non-default atf package, which runs your own existing Automated Test Framework tests through the official CI/CD API — it executes code on the instance by design, so it is meant for non-production environments.

Why is the npm package servicenow-mcp-ai?

The unscoped servicenow-mcp name was already taken on npm, so the package ships as servicenow-mcp-ai. The GitHub repository is IvanBBaev/servicenow-mcp-ai. The difference is cosmetic. This is an independent project, not affiliated with or endorsed by ServiceNow, Inc.; "ServiceNow" is a trademark of ServiceNow, Inc., used here only to indicate compatibility.

Can I run prod and dev from one server?

Yes — that's what named profiles are for. Define SN_PROFILE_PROD_* and SN_PROFILE_DEV_*, make prod read-only, and route a single call to a specific instance with the automatic instance argument, or switch the active one with servicenow_use_instance.

Which clients work?

Any MCP client over stdio — Claude Desktop, Claude Code, VS Code Chat, the MCP Inspector, and others. The server declares tool annotations so clients can apply the right confirmation UX for destructive actions.

Is it production-ready?

The engineering is: clean gates, ~200 tests, type-checked lint, a CI matrix and a security model. It is an open-source project under the MIT license — review the security model for your own deployment.