Drive ServiceNow from your AI assistant.

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.

Quick start

You need Node.js 20+ and a ServiceNow instance you can reach (a free Personal Developer Instance works great).

1 · Register the server with your MCP client

Point the server command at npx — no clone required. For Claude Desktop, add this to your claude_desktop_config.json; for VS Code use .vscode/mcp.json.

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

Where that file lives:

• Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) · %APPDATA%\Claude\claude_desktop_config.json (Windows).
• Claude Code (CLI) — claude mcp add servicenow -- npx -y servicenow-mcp-ai.
• VS Code — a .vscode/mcp.json in your workspace.

2 · Give it credentials

Create a .env file (the server also reads ~/.config/servicenow-mcp-ai/.env and real environment variables, which take precedence):

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 rotate credentials at runtime by asking the assistant to use servicenow_set_credentials.

3 · 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. Want to verify the connection first? Ask it to run servicenow_test_connection.

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.

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, docs, instance, email.

# 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

65 tools across 18 packages. read tools never mutate the instance; write tools respect the read-only and policy guards.

table — record CRUD

schema — metadata

aggregate · attachment · importset · batch

cmdb — class-aware CIs (IRE)

catalog · change · knowledge · email — plugin APIs

scripts — code intelligence (read-only)

flows — flow intelligence (read-only)

codecheck — local code analysis

docs · instance — documentation & environments

atf — Automated Test Framework (opt-in, non-default)

admin — always on

Use cases

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

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

Does the AI run code on my instance?

No. There is no background-script execution. Everything goes through documented REST APIs, and writes obey the policy and read-only guards. Automated test execution (ATF) over the official CI/CD API is a planned future addition.

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 LeassTaTT/servicenow-mcp. 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.