Servicenow Mcp Ai MCP Server

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.

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

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

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

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.

Supported authentication methods

Every inbound REST auth method ServiceNow offers is covered:

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 for a template.

Run / debug

• VS Code: open the Command Palette and start the server defined in .vscode/mcp.json, then use it from Chat.
• MCP Inspector: npm run inspector
• Directly: npm start

Develop

npm run check     # full gate: build, lint, format check, coverage-gated tests, prod audit
npm test          # unit tests only (node:test; needs a prior npm run build)
npm run lint      # ESLint (flat config + typescript-eslint)
npm run format    # format with Prettier

See CONTRIBUTING.md for the conventions (one commit per task, tests ship with the change, generated docs).

Tools

This table is generated from the tool registrations — edit the tool definitions in src/tools/, then run npm run docs:readme.

All tools carry MCP annotations (readOnlyHint, destructiveHint, idempotentHint) so clients can apply the right confirmation UX.

Tool packages

Tools are grouped into packages so you can 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 below.
• Individual packages: table, schema, aggregate, attachment, importset, batch, catalog, change, knowledge, cmdb, scripts, flows, codecheck, docs, instance, email, atf.

The admin tools (servicenow_set_credentials, servicenow_get_status) are always registered, regardless of the active packages. Unknown names are ignored. servicenow_get_status reports the resolved enabledPackages.

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

Examples

Query the 5 most recent active incidents:

// servicenow_query_table
{
  "table": "incident",
  "query": "active=true^ORDERBYDESCsys_created_on",
  "fields": ["number", "short_description", "priority", "state"],
  "limit": 5,
}

Create an incident:

// servicenow_create_record
{
  "table": "incident",
  "fields": {
    "short_description": "Printer on 3rd floor is down",
    "urgency": "2",
    "impact": "2",
  },
}

Update credentials at runtime:

// servicenow_set_credentials
{
  "instance": "dev98765.service-now.com",
  "user": "admin",
  "password": "••••••",
}

Resources

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

Prompts

Ready-made workflows are exposed as MCP prompts; they orchestrate the tools and insist on reading real values from the instance:

Project structure

.
├── .env                   # credentials (git-ignored; or ~/.config/servicenow-mcp-ai/.env)
├── .env.example           # template
├── .github/workflows/     # CI: build + lint + test
├── .vscode/mcp.json       # VS Code MCP server registration
├── eslint.config.js       # ESLint flat config
├── .prettierrc.json       # Prettier config
├── src/
│   ├── index.ts           # bootstrap: load env, register, connect stdio
│   ├── registry.ts        # registers all tool groups
│   ├── resources.ts       # MCP resources (status, tables, schema, docs)
│   ├── prompts.ts         # MCP prompts (triage, change impact, document table)
│   ├── http.ts            # shared REST client (auth, retry, SSRF)
│   ├── auth.ts            # Basic + OAuth 2.0 providers
│   ├── host.ts            # host resolution + SSRF guard
│   ├── policy.ts          # table allow/deny + read-only guards
│   ├── settings.ts        # numeric env settings
│   ├── logging.ts         # structured stderr logger
│   ├── result.ts          # tool results + structured errors
│   ├── servicenow.ts      # Table API client
│   ├── config.ts          # env file read/write + location
│   ├── api/               # aggregate, attachment, import set, batch, catalog, change, knowledge, cmdb, scripts, diagrams, docs, meta
│   └── tools/             # tool registration per API group
├── test/                  # node:test unit + mock-fetch tests
└── build/                 # compiled output (after npm run build)

Note on names: the npm package is servicenow-mcp-ai (the unscoped servicenow-mcp was already taken); the GitHub repository is servicenow-mcp; the local working folder is sincronia-mpc (a historical mpc/mcp typo). All three differences are cosmetic and do not affect the build or runtime.

Security notes

• The env file is git-ignored — do not commit real credentials.
• The env file is written owner-only (0600) — it holds a plaintext password.
• The server uses the stdio transport and only logs to stderr; secrets and raw encoded queries are never logged.
• The password/token is never returned by any tool.
• Hosts are restricted: without SN_ALLOWED_HOSTS, only *.service-now.com instances are contacted (internal/loopback always blocked), so a redirected or mistyped host cannot silently receive credentials. Set SN_ALLOWED_HOSTS to opt in a custom or sovereign-cloud domain.
• Prefer OAuth 2.0 over Basic where possible (SN_OAUTH_CLIENT_ID).
• Apply least privilege with SN_TABLES_ALLOW / SN_TABLES_DENY and SN_READONLY=true for read-only deployments.
• Table policy does not cover plugin APIs. SN_TABLES_DENY=change_request blocks the Table API path, but the Change Management API (sn_chg_rest) can still read/write changes. To restrict the plugin-backed surfaces use SN_PACKAGES_DENY (drop the whole package) or SN_PACKAGES_READONLY (register only its read tools). The Batch API obeys both axes too: a sub-request to a denied package's path is refused, and writes to a read-only package are blocked — a batch cannot be used to bypass the package policy.

Project documentation

Trademark

servicenow-mcp-ai is an independent, community-built project. It is not affiliated with, endorsed by, or sponsored by ServiceNow, Inc.

"ServiceNow", the ServiceNow logo, "Now", and related marks are trademarks or registered trademarks of ServiceNow, Inc. in the United States and other countries. They are used in this project's name and documentation only nominatively — to identify the platform this software interoperates with — and no affiliation or endorsement is implied. All other product names and marks are the property of their respective owners.

This project is licensed under the MIT License; that license covers the source code and does not grant any rights to use the ServiceNow trademarks.