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 2.x? 3.0 has breaking defaults (plan tokens for destructive applies, protected system tables, a smaller default tool set). Run npx servicenow-mcp-ai migrate --write once: it carries your env file and MCP client config over and adds SN_COMPAT=2, which keeps every 2.x default you have not set. See the CHANGELOG → "Migration at a glance" for each change.

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, 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, the event 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, safe write, drift review, schema impact, instance discovery) that orchestrate the tools; every plugin skill has a prompt twin for clients without the plugin.
• Tool packages: load only the tool groups you need via SN_TOOL_PACKAGES (default profile discovery; 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_cred