Servicenow MCP AI

servicenow-mcp-ai — ServiceNow MCP Server

📖 [Documentation site →](https://ivanbbaev.github.io/servicenow-mcp-ai/)

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