Home

servicenow-mcp-ai

A Model Context Protocol server that lets an MCP client (VS Code, Claude Desktop, Cursor, …) drive a ServiceNow instance over its REST surface: 67 tools in 18 packages, plus script intelligence, flow tracing, multi-instance profiles, plan-and-apply write safety, a two-axis access policy and deterministic Mermaid generators.

📖 Documentation site → · 📦 npm: servicenow-mcp-ai · 💻 Repository

---

What it does

Point your MCP client at an instance and ask in natural language — the server turns it into the right REST calls:

• "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 (servicenow_where_used). The IDE-grade find usages ServiceNow has no button for.
• "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 (servicenow_trace_table_event).
• CRUD on any table — query, read, create, update, delete, with encoded queries, field selection and pagination — behind plan-by-default write safety (see below).

Key capabilities

• Full Table API plus Aggregate (Stats), Attachment, Import Set, Batch and table/column metadata (sys_db_object, sys_dictionary).
• Process & plugin APIs — CMDB (class-aware CI CRUD via IRE), Service Catalog, Change Management (typed creation + conflict detection) and Knowledge. 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), all read-only over the Table API.
• Flow tracing & code checking — deterministic table-event tracing, Flow Designer reads with run history, a local linter and an aggregate code-health report with an ACL security scan. Run ATF tests via the CI/CD API (opt-in).
• Self-documentation — a local Markdown knowledge base (read/write/search) plus Mermaid generators (ER diagrams, record-lifecycle flowcharts).
• Multi-instance profiles — snapshot an instance's structure locally and diff two profiles.
• Plan-and-apply write safety — writes return a non-mutating preview unless you pass apply: true, with a local journal of applied changes.
• Least-privilege — table allow/deny lists, a global read-only mode and a two-axis access policy; the password/token is never echoed back.

Quick start

npx servicenow-mcp-ai        # run the server (stdio)

Then register it with your MCP client and set the connection env vars (SN_INSTANCE_URL, auth credentials). OAuth 2.1 (Authorization Code + PKCE) is recommended; Basic and OAuth 2.0 are supported too.

➡️ Full walkthrough: Setup · Configure credentials · Run / debug

Tool packages

Expose only the groups a client needs via SN_TOOL_PACKAGES (fewer tools keep the model focused). Three named presets cover the common roles:

Preset	SN_TOOL_PACKAGES=…	For whom
reader	table,schema,aggregate	Analysts, first contact — read and query only.
developer	table,schema,aggregate,scripts,flows,codecheck,docs	Script intelligence, flow tracing, linting, docs & diagrams.
admin	all	Everything, including plugin and write-heavy packages.

Default profile is core (table, schema, aggregate, attachment). The admin tools are always registered. Individual packages: table, schema, aggregate, attachment, importset, batch, catalog, change, knowledge, cmdb, scripts, flows, codecheck, docs, instance, email, atf.

➡️ Full tool table: Tools

Write safety (v2.0+)

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). Applied changes are recorded in a local journal.

➡️ Migration note: CHANGELOG → 2.0.0

Documentation map

Resource	Where
Documentation site	https://ivanbbaev.github.io/servicenow-mcp-ai/
README (full reference)	README.md
Architecture	project/ARCHITECTURE.md
Product state	project/PRODUCT-STATE.md
Roadmap	project/ROADMAP.md
Changelog	CHANGELOG.md
Security policy	SECURITY.md
Contributing	CONTRIBUTING.md

Requirements

• Node.js 20+ (enforced via engines and a runtime guard; the project targets the version in .nvmrc).

Support

Built and maintained in personal time — if it helps, a GitHub Sponsors tip keeps it going. Report issues on the issue tracker.

---

_{ServiceNow is a registered trademark of ServiceNow, Inc. This is an independent, unaffiliated project.}