sn-mcp
A ServiceNow MCP server exposing 52 tools (per this schema) for read/write administration of incidents, users/groups, service catalog, change/changesets, and knowledge bases, plus two read-only reporting tools.
Reports (read-only):
get_syslog_report(warnings/errors for a date, default yesterday) andget_developer_work_report(sys_update_xml changes between two dates, grouped by author/update set).Incidents: create, update, list (paginated/filterable), fetch by number, add customer-visible comments or internal work notes, and resolve with a resolution code/notes.
Users & groups: create/update/get/list users (with role assignment), create/update/list groups, and add/remove group members (deduped).
Service catalog: list/get/update catalog items, list/create/update categories, move items between categories, create/list/update catalog item variables, and fetch optimization recommendations (partially simulated — low_usage/high_abandonment/slow_fulfillment are randomly fabricated).
Change & changeset: create/update/list/get change requests, add change tasks, submit/approve/reject (may fail due to Change Model rules on this PDI), and full changeset (update set) lifecycle — create/update/list/get/commit/publish/add file — with known ACL and missing-state caveats.
Knowledge base: create/list knowledge bases, create categories, create/update/list/get articles, and attempt to publish articles (direct
workflow_statewrites silently revert to draft on this PDI).Common behavior: list tools return one bounded page via
limit/offsetrather than the whole table; many write tools accept a sys_id, number, username/email, or name and resolve it internally.Not in this schema (despite the README's 78-tool claim): Story/Scrum/Project, Script Include, classic Workflow, and docs search tools are absent here.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@sn-mcp Show me update set changes from the last week."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
sn-mcp
Local MCP server for ServiceNow: 78 tools across 15 domains — incidents, changes, catalog, knowledge base,
users/groups, script includes, Agile (story/scrum task/project), classic Workflow, and the two original
on-demand reports the project started as. Most of that surface is a full read/write port of
echelon-ai-labs/servicenow-mcp, a larger Python/FastMCP
ServiceNow server. Built from a plan kept in the author's private Obsidian vault ("ServiceNow MCP Server —
Syslog & Dev Work Reports (Plan)"); the full read/write port that took this from 2 tools to 78 followed its
own separate plan, preserved at C:\Users\willr\.claude\plans\structured-spinning-rain.md. Setup narrative
and troubleshooting also live in that vault, in a matching "(Setup Guide)" note — not included in this repo.
Borrowed from the reference project: a remote-reachable HTTP transport alongside stdio (step 7 below) — it
exposes both stdio and SSE, this project uses stdio and the modern Streamable HTTP equivalent; ServiceNow's
own relative-date keywords informed comparing against this project's own date-range query style, which is
what originally surfaced the timezone bug described in step 4/Troubleshooting; and (from the full port) its
82-tool inventory across 14 domains, ported with full read/write parity per an explicit user decision — not
its AuthManager (Basic/OAuth/API-key behind one interface), which stays out of scope; this project remains
Basic-only.
Build history
Commit | What |
| Original build: |
| Batch 0+1 of 8 — write CRUD layer ( |
| Batch 2 of 8 — User & Group tools. |
| Batch 3 of 8 — Catalog tools. |
| Batch 4 of 8 — Change & Changeset tools. |
| Batch 5 of 8 — Knowledge Base tools. |
| Batch 6 of 8 — Story, Scrum Task & Project tools; epic tools dropped (see gap list below). |
| Batch 7 of 8 — Script Include tools. |
| Batch 8 of 8 (final) — classic Workflow tools; 3 tools dropped (see gap list below). Port complete: 76/82 reference tools shipped. |
| Full README documentation pass: per-domain tool reference, dropped-tool rationale, corrected account-provisioning guidance. |
Each batch was verified end-to-end through real MCP tool calls (not just direct function tests) before
committing — create/update/list at minimum, with test data tagged [MCP-TEST] and cleaned up afterward.
Full per-batch build notes, gotchas, and platform-specific findings live in project memory, not this file.
Of the reference's 82 tools, 76 were ported (giving 78 total with the 2 original report tools). 6 were deliberately not ported — not porting mistakes, each confirmed against this PDI's live schema before being dropped:
create_epic/update_epic/list_epics—rm_epicis not a valid table on this PDI (confirmed viasys_db_object; this instance's Agile plugin install is scrum-only, no Epic/Project-portfolio linkage).activate_workflow/deactivate_workflow—wf_workflowhas noactivefield on this PDI at all (confirmed by dumping every element on the table).reorder_workflow_activities—wf_activityhas noorderfield either; classic Workflow ordering here is driven by a visual transition graph, not a simple integer.
get_optimization_recommendations is ported but partially simulated — see its entry below.
percent_complete on the project tools is intentionally renamed from the reference's percentage_complete,
which is a genuine bug in the reference project (doesn't match the real pm_project column, so it silently
no-ops there). Full per-batch build notes, gotchas, and platform gaps live in project memory
(project_servicenow_mcp_reports.md) and in code comments at each domain file (src/tools/*.ts).
Related MCP server: servicenow-mcp
Tools
Reports (read-only)
Both are read-only GET queries against the Table API — neither tool ever writes to the instance. Both
return raw/grouped rows only; analysis (suggested fixes, flagged concerns) happens in conversation with
Claude, not inside the tool. Both paginate automatically (queryTableAll in servicenow-client.ts, 1000
rows/page, 10,000-row safety cap) instead of a hardcoded single-page sysparm_limit — if a query hits the
cap, the response leads with an explicit ⚠ Truncated text block before the JSON, rather than silently
returning a partial report. Registered for both entrypoints from the same src/create-server.ts.
get_syslog_report
Fetch syslog rows for a single day, filtered to warning/error by default.
Parameter | Type | Required | Default | Notes |
|
| no | yesterday |
|
|
| no |
| Friendly names ( |
Returns a JSON array of:
{
"sys_created_on": "2026-08-25 17:30:24",
"message": "SG-Azure Request failed with statusCode: 403 Code: AccessDenied ...",
"source": "sn_sg_azure_integ",
"level": "2",
"node": "..."
}get_developer_work_report
Fetch sys_update_xml changes between two dates, grouped by author and update set.
Parameter | Type | Required | Default | Notes |
|
| yes | — |
|
|
| yes | — |
|
Returns a JSON array of:
{
"author": "system",
"updateSet": "Default",
"isDefaultUpdateSet": true,
"changeCount": 2,
"changes": [
{ "name": "...", "type": "Service Graph Connections State", "created": "2026-08-25 10:30:30" }
]
}Docs search — ServiceNow + Moveworks (src/tools/docs.ts + src/docs/docs-client.ts, 3 tools)
Read-only full-text search over two local SQLite FTS5 indexes:
Source | Corpus | Builder | Citation URL |
| Official ServiceNow product docs, one index per release (~46k files each); pick with |
|
|
| Mirror of docs.moveworks.com (~800 pages), optional |
| the live |
This server never re-implements indexing. It reads the DBs those builders produce, and (via
docs_reindex) calls them to rebuild.
One source of truth, no drift. The index shape — columns, porter unicode61 tokenizer, bm25
weights (title 10 > breadcrumb 6 > description 4 > body 1), and the query tokeniser — is
defined once in ServiceNowDocs/tools/index_schema.json. MoveworksDocs/tools carries a copy, so
both indexes have the same shape. Each builder writes a copy (a sidecar, index_schema.json)
next to every DB it produces, and docs-client.ts reads that sidecar per source. So a DB always
carries the exact schema it was built with. If no sidecar/schema is found, the reader falls back to a
built-in default that mirrors the JSON.
Snippets are for ranking only — call docs_get to read a doc in full before quoting it.
Env: SN_DOCS_DB (path to the ServiceNow docsearch.db; baked in the container, point at your
checkout locally), SN_DOCS_SCHEMA (schema location; defaults to the sidecar beside the DB),
SN_DOCS_BRANCH (the release SN_DOCS_DB holds — the default release), SN_DOCS_DB_<RELEASE> (one per
extra release, e.g. SN_DOCS_DB_BRAZIL), and for docs_reindex: SN_DOCS_REPO (a
ServiceNowDocs checkout), SN_DOCS_BUILDER / SN_DOCS_PYTHON (overrides). Moveworks: MW_DOCS_DB,
MW_DOCS_SCHEMA, MW_DOCS_REPO, MW_DOCS_BUILDER (same meanings; SN_DOCS_PYTHON is shared).
Leave MW_DOCS_DB empty to run without Moveworks — both searches then skip it. See .env.example.
docs_search
Ranked full-text search. Returns hits with source, title, citation URL, path, publication,
topic_type, last_updated, a snippet, and match (how the hit was found). The phrase/all/some plan
mirrors index_schema.py's match_plan, so the MCP and query_index.py return the same hits. With source: "both", it takes up to limit hits from each
source and interleaves them by rank (bm25 scores from two indexes aren't comparable).
Parameter | Type | Required | Default | Notes |
|
| yes | — | Plain query runs up to three searches: the exact phrase (2–4 words), then all words, then any word to fill the remaining slots. Stopwords are dropped first (list in the schema's |
|
| no |
|
|
|
| no |
| ServiceNow release, e.g. |
|
| no |
| 1–25, per source. |
|
| no |
| Pass the query as literal FTS5 syntax ( |
docs_get
Fetch one indexed doc in full (fields + body) by its repo-relative path and source from a
docs_search hit.
Parameter | Type | Required | Default | Notes |
|
| yes | — | e.g. |
|
| no | try ServiceNow, then Moveworks | Pass the hit's |
|
| no |
| ServiceNow only. Pass the hit's |
docs_reindex
Rebuild one index by running its build_index.py, then reopen the DB so searches use the fresh
index. The server closes its own handle first (Windows locks open files); another process holding
the same DB open still blocks the rebuild. Not available in the baked container image (it ships
one release's ServiceNow index and drops the markdown tree).
Parameter | Type | Required | Default | Notes |
|
| no |
| ServiceNow takes minutes (~46k files, needs |
|
| no |
| ServiceNow only. Which release's index to rebuild; it writes to that release's DB and stamps its citation URLs. The builder reads the checked-out branch, so that branch must match |
Incident (src/tools/incident.ts, 6 tools)
assigned_to/assignment_group/caller_id accept a username, email, or sys_id, written as display
values. resolve_incident's resolution_code is a choice field — verified against sys_choice on this PDI
rather than guessed (see project memory for the confirmed value list).
Tool | Description |
| Create a new incident. |
| Update an existing incident (accepts sys_id or incident number). |
| Add a comment or work note to an incident. |
| Resolve an incident (sets state to Resolved with a resolution code and notes). |
| List incidents, most recent first. One bounded page per call, not the full table. |
| Fetch a single incident by its number (e.g. INC0010001). |
User & Group (src/tools/user.ts, 9 tools)
user_id/group_id accept a raw sys_id, username/email, or group name. Group-membership adds dedupe
against existing rows before inserting (a deliberate improvement over the reference, which doesn't).
Tool | Description |
| Create a new user. |
| Update an existing user (accepts sys_id, username, or email). |
| Fetch a single user by sys_id, username, or email. |
| List users, most recent first. One bounded page per call. |
| Create a new group, optionally with initial members. |
| Update an existing group (accepts sys_id or name). |
| Add one or more members to a group. |
| Remove one or more members from a group. |
| List groups. One bounded page per call. |
Catalog (src/tools/catalog.ts + catalog-variables.ts + catalog-optimization.ts, 11 tools)
get_optimization_recommendations is partially simulated: low_usage/high_abandonment/
slow_fulfillment are randomly fabricated (no real usage-tracking data source exists on this PDI, matching
the reference project's own use of Python's random), while inactive_items/description_quality reflect
real instance data — the whole response is still labeled simulated: true rather than splitting the
labeling per-type, a deliberate choice. Never present this tool's output as real analysis.
Tool | Description |
| List service catalog items. One bounded page per call. |
| Fetch a single catalog item by sys_id, including its variables (form fields). |
| List service catalog categories. One bounded page per call. |
| Create a new service catalog category. |
| Update an existing service catalog category. |
| Move one or more catalog items to a different category. |
| Create a new variable (form field) on a catalog item. |
| List the variables (form fields) defined on a catalog item. |
| Update an existing catalog item variable. |
| SIMULATED optimization recommendations — see note above. |
| Update an existing catalog item's core fields. |
Change & Changeset (src/tools/change.ts + changeset.ts, 15 tools)
Known platform gaps on this PDI (not porting bugs — confirmed empirically, documented in each tool's own
MCP description): submit_change_for_approval/approve_change/reject_change's state transitions are
blocked by a Change Model business rule, and sysapproval_approver.document_id doesn't persist via direct
write — approval records are meant to come from ServiceNow's own Approval Engine. add_file_to_changeset
is blocked by ACL on sys_update_xml. publish_changeset's "published" state doesn't exist as a
sys_update_set choice on this PDI (silently no-ops rather than erroring). All four tools are still
implemented as faithful ports — the gaps are platform behavior, not something this project codes around.
Tool | Description |
| Create a new change request. |
| Update an existing change request (accepts sys_id or change number). |
| List change requests. One bounded page per call. |
| Fetch a single change request with its associated change tasks. |
| Add a task to a change request. |
| Submit for approval. NOTE: may fail — see gaps above. |
| Approve a pending approval record and move to Implement. NOTE: may fail — see gaps above. |
| Reject a pending approval record and cancel the change. NOTE: may fail — see gaps above. |
| List changesets (update sets). One bounded page per call. |
| Fetch a single changeset with the changes it contains. |
| Create a new changeset. |
| Update an existing changeset (accepts sys_id or name). |
| Commit a changeset (sets state to complete). |
| Publish a changeset. NOTE: may silently no-op — see gaps above. |
| Add a file to a changeset. NOTE: often ACL-blocked — see gaps above. |
Knowledge Base (src/tools/knowledge-base.ts, 9 tools)
publish_article's direct workflow_state write silently reverts to draft on this PDI — modern instances
drive publish through Flow Designer (kb_publish_flow), not a bare Table API write; documented in the
tool's own description rather than fixed, since resolving the flow is out of scope. kb_category/
kb_knowledge_base block direct deletes via ACL even for this admin-scoped account — no cleanup path exists
through the Table API for those two tables.
Tool | Description |
| Create a new knowledge base. |
| List knowledge bases. One bounded page per call. |
| Create a new category in a knowledge base. |
| Create a new knowledge article. |
| Update an existing knowledge article. |
| Change an article's workflow state. NOTE: silently reverts to draft — see note above. |
| List knowledge articles. One bounded page per call. |
| Fetch a single knowledge article by sys_id. |
| List knowledge base categories. One bounded page per call. |
Story, Scrum Task & Project (src/tools/story.ts + scrum-task.ts + project.ts, 12 tools)
Epic tools and story.epic/story.project/scrum_task.type params dropped — see the top-of-file gap list.
percent_complete on the project tools is renamed from the reference's percentage_complete (a genuine bug
in the reference — that name doesn't match the real pm_project column).
Tool | Description |
| Create a new story. |
| Update an existing story (accepts sys_id or story number). |
| List stories. One bounded page per call. |
| List dependencies between stories. |
| Create a dependency between two stories. |
| Delete a story dependency record. |
| Create a new scrum task under a story. |
| Update an existing scrum task (accepts sys_id or scrum task number). |
| List scrum tasks. One bounded page per call. |
| Create a new project. |
| Update an existing project (accepts sys_id or project number). |
| List projects. One bounded page per call. |
Script Include (src/tools/script-include.ts, 5 tools)
Highest-care domain in this project — script is live, executable server-side JavaScript. Never write
code from an untrusted source through these tools. script_include_id accepts a name, or a sys_id prefixed
with sys_id: to bypass name lookup.
Tool | Description |
| List script includes (metadata only, not script bodies). One bounded page per call. |
| Fetch a single script include, including its full script body. |
| Create a new script include. WARNING: live executable code. |
| Update an existing script include. WARNING: live executable code. |
| Delete a script include. |
Workflow (src/tools/workflow.ts, 9 tools)
Classic Workflow — legacy, superseded by Flow Designer on modern instances. Confirmed live and queryable on
this PDI before porting. activate_workflow/deactivate_workflow/reorder_workflow_activities are not
ported — see the top-of-file gap list. add_workflow_activity's activity_type resolves by name against
wf_activity_definition (the real reference field), not a flat string as the reference project assumes.
Known reference-project gap, ported as-is: add_workflow_activity requires a real workflow_version_id
that no tool in this domain creates — create_workflow makes an empty wf_workflow row with no version;
get one via list_workflow_versions against a pre-existing workflow, or create one directly via the Table
API (not exposed as a tool here, matching the reference's own scope).
Tool | Description |
| List classic Workflow definitions. One bounded page per call. |
| Fetch a single workflow definition, optionally including its versions. |
| List the versions of a workflow. |
| Fetch activities for a workflow version, defaulting to the latest published version. |
| Create a new (empty) workflow definition. |
| Update an existing workflow definition (accepts name or sys_id). |
| Add an activity to a workflow version. See gap note above. |
| Update an existing workflow activity's name or extra fields. |
| Delete a workflow activity. |
1. Provision authentication (manual, one-time)
Authentication is OAuth 2.0 inbound JWT bearer grant, not Basic auth. The server signs a short-lived
JWT with an RSA private key and exchanges it at /oauth_token.do for an access token; ServiceNow verifies
the signature against the matching public certificate. No user password is stored or sent. Full reference:
Create an OAuth JWT API endpoint for external clients
(Australia release).
1a. Generate an RSA keypair (on this machine)
# Private key stays here; the server signs JWTs with it. Keep it out of git.
openssl genrsa -out sn-mcp-private-key.pem 2048
# Self-signed public cert to upload to ServiceNow (10-year validity here — adjust as you like).
openssl req -new -x509 -key sn-mcp-private-key.pem -out sn-mcp-public-cert.pem -days 3650 -subj "/CN=sn-mcp"Point SN_JWT_KEY_PATH in .env at sn-mcp-private-key.pem.
1b. Provision a service user
User Administration → Users → New, logged in as admin. Give it a stable identifier the JWT sub will
carry — e.g. an Email or User ID. Add roles per the guidance below. (You no longer need "Web
service access only" — that flag only mattered for Basic auth's SNCRestrictBasicAuthUserAuthenticationGate;
OAuth bearer tokens don't hit that gate.)
1c. Upload the cert and create the JWT endpoint
All → Multi-Provider SSO → x509 Certificate (or the X.509 Certificates /
sys_certificatetable) → New → paste the contents ofsn-mcp-public-cert.pem, Type PEM, Active = true.System OAuth → Application Registry → New → "Create an OAuth JWT API endpoint for external clients".
User Field: the sys_user field the JWT
submatches (e.g. Email). This is how the token gets an operating user for ACLs.Set Access Token Lifespan as you like (default ~1799s). Leave JTI verification on (the server sends a fresh
jtieach exchange).Save, then record the auto-generated Client ID and Client Secret (or tick Public Client to skip the secret).
On that endpoint → JWT Verifier Maps related list → New:
Kid: pick a value (e.g.
sn-mcp) — this must equalSN_JWT_KIDin.env.Sys certificate: the cert record from step 1.
Required claims (
iss,aud,sub,exp) need no OAuth JWT Claim Validations records.audandissboth default to the Client ID in this server; if your endpoint expects a differentiss, add it as a claim validation and setSN_OAUTH_ISSUER.
1d. Fill in .env
Copy .env.example to .env and set SN_INSTANCE, SN_CLIENT_ID, SN_CLIENT_SECRET, SN_JWT_KEY_PATH,
SN_JWT_KID, and SN_JWT_SUBJECT (the value ServiceNow will match via User Field).
Role scope (unchanged by the auth switch). The mapped service user carries whatever roles you grant it —
that governs what the tools can do, exactly as before. Start read-only (rest_api_explorer plus read on
syslog/sys_update_xml/sys_update_set) if you only want the two report tools, and grant roles per
domain as each write tool is actually needed. Script include writes are effectively code-execution
capability and deserve the most scrutiny of any grant — see the Script Include tools section above.
2. Build
cd C:\Users\willr\projects\sn-mcp
npm install
npm run build3. Verify auth before wiring into a client
With .env filled in and the project built:
npm run auth:testIt mints a JWT access token and does one sys_user read. Prints OAuth JWT authentication verified on
success. If it fails: 401 = the signature or claims were rejected (check SN_JWT_KID matches the JWT
Verifier Map's Kid, the uploaded cert matches the private key, and aud/iss = Client ID, and sub
matches the endpoint's User Field); 403 = the token is valid but the mapped user lacks a role for
that table.
4. syslog table name, level values, and date filtering (resolved)
Confirmed against this instance on 2026-08-26:
The table is
syslog, notsys_log(sys_logreturns400 Invalid table sys_log).syslog.levelis numeric, not the strings"warning"/"error":-2=Trace, -1=Debug, 0=Information, 1=Warning, 2=Error, 3=Fatal(confirmed viaGET /api/now/table/sys_choice?sysparm_query=name=syslog^element=level).The date-range filter must use plain literal datetimes (
'<date> 00:00:00'@'<date> 23:59:59'), notjavascript:gs.dateGenerate(...)— see Troubleshooting for why the latter silently shifted results onto the wrong day.
src/tools/syslog.ts maps friendly level names ("warning", "error", etc.) to these codes internally, so
callers can keep passing names — this only matters if you extend the tool or point it at a different
instance, where the mapping should be re-verified with the same sys_choice query.
5. Register with Claude Code CLI
claude mcp add --scope user sn-mcp -- "C:\Program Files\nodejs\node.exe" C:\Users\willr\projects\sn-mcp\dist\index.jsUse the absolute path to node.exe, not bare node — a Claude Code session started before Node was on
PATH won't be able to resolve a bare node command when spawning the server (claude mcp list will show
CONNECTION_CLOSED). Verify with claude mcp list.
Claude Code CLI reads the SN_* OAuth JWT variables from .env in this project folder — no extra env
config is needed on the CLI side as long as .env exists here. This relies on src/index.ts resolving
.env's path relative to the compiled script itself (import.meta.url), not process.cwd() — plain
import "dotenv/config" would fail, because Claude Code spawns this server from an unrelated working
directory. See Troubleshooting if .env ever seems to stop loading.
6. Register with Claude Desktop
Add to %APPDATA%\Claude\claude_desktop_config.json (created fresh — didn't exist on this machine):
{
"mcpServers": {
"sn-mcp": {
"command": "C:\\Program Files\\nodejs\\node.exe",
"args": ["C:\\Users\\William.Wood\\Repos\\sn-mcp\\dist\\index.js"],
"env": {
"SN_INSTANCE": "https://devXXXXXX.service-now.com",
"SN_CLIENT_ID": "<client id>",
"SN_CLIENT_SECRET": "<client secret>",
"SN_JWT_KEY_PATH": "C:\\Users\\William.Wood\\Repos\\sn-mcp\\sn-mcp-private-key.pem",
"SN_JWT_KID": "sn-mcp",
"SN_JWT_SUBJECT": "<service user email or user_name>"
}
}
}
}Desktop launches the server as its own process without inheriting this project's .env, so the connection
settings are repeated here explicitly. Restart Claude Desktop after editing, then check the 🔌 connector icon to
confirm it connected.
7. Optional: remote-reachable HTTP transport
Steps 5–6 use stdio, which only works for a client that can spawn a local process (Claude Code, Claude
Desktop). A client that can't — e.g. claude.ai's hosted Scheduled Tasks — needs an HTTP endpoint instead.
src/http.ts exposes the same two tools over MCP's Streamable HTTP transport at POST/GET /mcp.
npm run build
$env:MCP_HTTP_TOKEN="<pick something random>"; npm run start:httpDefaults: binds 127.0.0.1:3535 (override with MCP_HTTP_HOST / MCP_HTTP_PORT in .env). If
MCP_HTTP_TOKEN is set, every request must send Authorization: Bearer <token> or gets 401; if unset,
the server logs a warning and accepts unauthenticated requests — fine while bound to localhost only, not
fine if this ever sits behind a public tunnel. createMcpExpressApp() (from the SDK) also enables DNS-rebinding
protection automatically whenever bound to a localhost host.
To actually reach this from claude.ai's hosted Scheduled Tasks, 127.0.0.1 isn't enough — it needs a
public URL (e.g. a tunnel: ngrok http 3535, or a real deployment). That's a separate step, not done here;
this just adds the capability. Smoke test locally first:
curl.exe -s -X POST http://127.0.0.1:3535/mcp -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" -H "Authorization: Bearer $env:MCP_HTTP_TOKEN" -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"smoketest","version":"0.0.1"}}}'Should return 200 with a mcp-session-id response header and a JSON-RPC result body.
Troubleshooting
Three gotchas found setting up PDI dev386580 on 2026-11-02. All three show up as the same
401 {"error_description":"access_denied","error":"server_error"} from auth:test, so check each one:
Client secret contains
#— dotenv treats an unquoted#as the start of a comment and silently truncates the secret (32 chars became 17). Always single-quote it in.env:SN_CLIENT_SECRET='...'. Single quotes also keep$literal.No auth scope on the endpoint — new OAuth entities are "Securely scoped" with no Auth Scope, which logs
invalid_scope: The provided OAuth token is not valid. Add the existinguseraccountauth scope to the endpoint (don't create a new one with that name — it's checked by sys_id).Service user has
admin— the token endpoint returnsGrant access token to admin is not allowed. Give the user specific roles instead (currently:itil,itil_admin,catalog_admin,knowledge_admin,user_admin,sn_change_write,rest_api_explorer,workflow_admin,oauth_admin). Tools that need fulladmin(script include writes, update set publishing) will return 403.
To see the real reason behind the generic 401, call /oauth_token.do directly with the same assertion:
it returns 400 invalid_grant with a specific error_description.
401 on every REST call — with OAuth JWT this is a rejected assertion or token, not a password. Check:
SN_JWT_KIDequals the endpoint's JWT Verifier Map Kid; the uploaded cert is the public half ofSN_JWT_KEY_PATHand is Active;aud/iss= Client ID; andSN_JWT_SUBJECTmatches a sys_user via the endpoint's User Field. Runnpm run auth:test— it separates the token-mint step from the Table API call so you can see which one fails. (Historical note: under the old Basic-auth setup this same 401 was usuallySNCRestrictBasicAuthUserAuthenticationGate— the "Web service access only" flag — which no longer applies to OAuth bearer tokens.)Invalid table sys_log(HTTP 400) — the table issyslog, no underscore.Report comes back empty even though logs exist for that day —
levelis numeric on this instance (see step 4), not the strings"warning"/"error". Re-check the mapping via thesys_choicequery if pointing this at a different instance.Missing SN_INSTANCE(orSN_CLIENT_ID,SN_JWT_KEY_PATH, ...) environment variables when launched as a real MCP server, even though.envexists and a directnode dist/index.jstest from this folder works fine** — that direct test succeeds because itsprocess.cwd()happens to be the project folder; Claude Code launches the server from elsewhere, so plaindotenv/configfails silently. Confirmsrc/index.tsresolves.envviaimport.meta.url, not cwd (see step 5). Always verify with a real MCP tool call, not just a direct script run — the two can disagree.get_syslog_reportsilently returns the wrong day / is missing several hours — was a real bug, found 2026-08-26 via a spot-check comparison against echelon-ai-labs/servicenow-mcp's query patterns.src/tools/syslog.tsused to build the date filter withsys_created_onBETWEENjavascript:gs.dateGenerate('<date>','00:00:00')@javascript:gs.dateGenerate(...).gs.dateGenerate()evaluates in the instance's configured timezone, butsys_created_oncomes back as a raw UTC value over the Table API — so the window was silently offset by the instance's UTC delta (~7h on this PDI), pulling in the tail of the wrong day and missing early hours of the right one. Fixed by dropping thejavascript:gs.dateGenerate(...)wrapper entirely and passing plain literal'<date> 00:00:00'@'<date> 23:59:59'strings, which compare directly against the raw stored value with no timezone conversion. Verified: 834 rows across all 24 hours for 2026-08-25, vs. 366 rows across 17 hours before the fix. If this instance's timezone config ever changes, re-verify with the same full-hour-coverage check (see step 4-style spot check) rather than assuming.CONNECTION_CLOSEDinclaude mcp list— the CLI session started before Node.js was on PATH. Register withnode.exe's absolute path (already done in step 5) or start a fresh session.Edited the code, rebuilt, but behavior didn't change — an already-running Claude Code session keeps the old
dist/loaded over its stdio connection. Run/mcpin that session to reconnect; no restart needed.
Files
src/servicenow-client.ts— Table API wrapper (Basic Auth):queryTable/getRecord/createRecord/updateRecord/deleteRecord, plusqueryTableAll, the "fetch everything up to a safety cap" pagination loop the two report tools use (1000 rows/page, 10,000-row safety cap, returns{ rows, truncated }) — not used by anylist_*tool, which paginate one caller-controlled page at a time via plainqueryTable. Swap Basic Auth for OAuth here later if moving off the PDI.src/register-tool.ts—registerTool()/jsonResult(): shared response framing (JSON content block, prepends a⚠ Truncatednote when a result carries{truncated: true}) so every domain file doesn't hand-roll it.src/tools/shared.ts— cross-domain helpers:resolveUserSysId/resolveRoleSysId/resolveGroupSysId/assignRoleToUser(user/group/role lookups, reused byuser.tsand beyond) andbuildTimeframeQuery(theupcoming/in-progress/completedfilter shared bychange.ts/story.ts/scrum-task.ts/project.ts— deliberately built from a literal UTC timestamp, notjavascript:gs.now(), to avoid the timezone bug class described in Troubleshooting below).src/tools/syslog.ts,src/tools/dev-work-report.ts— the two original report queries.src/tools/incident.ts,user.ts,catalog.ts,catalog-variables.ts,catalog-optimization.ts,change.ts,changeset.ts,knowledge-base.ts,story.ts,scrum-task.ts,project.ts,script-include.ts,workflow.ts— the 76 ported tools, one file per reference domain; see the Tools section above for what's in each and project memory for the batch-by-batch build history.src/create-server.ts— builds anMcpServerand registers all 78 tools, grouped by domain with a comment header per section; shared by both entrypoints below.src/index.ts— stdio entrypoint (Claude Code/Desktop); resolves.envrelative to itself (not cwd).src/http.ts— Streamable HTTP entrypoint (step 7); bearer-token auth, one server+transport per session.
Available Tools
52 toolsadd_change_taskC
Add a task to a change request.
Inputs: change_id (required), short_description (required), assigned_to, description, +2 more.
add_commentB
Add a comment or work note to an incident.
Inputs: comment (required), incident_id (required), is_work_note.
add_file_to_changesetB
Add a file (sys_update_xml record) to a changeset. NOTE: sys_update_xml often blocks direct inserts via ACL (confirmed on this PDI) since it normally holds system-generated content.
Inputs: file_path (required), changeset_id (required), file_content (required).
add_group_membersA
Add one or more members to a group.
Inputs: members (required), group_id (required).
approve_changeA
Approve a change request's pending approval record and move the change to Implement. NOTE: may fail on instances with Change Model governance — confirmed on this PDI.
Inputs: change_id (required), approver_id, approval_comments.
commit_changesetC
Commit a changeset (sets state to complete).
Inputs: changeset_id (required), commit_message.
create_articleC
Create a new knowledge article.
Inputs: text (required), title (required), category (required), knowledge_base (required), +3 more.
create_catalog_categoryC
Create a new service catalog category.
Inputs: title (required), icon, order, active, +2 more.
create_catalog_item_variableC
Create a new variable (form field) on a catalog item.
Inputs: name (required), type (required), label (required), catalog_item_id (required), +10 more.
create_categoryB
Create a new category in a knowledge base.
Inputs: title (required), knowledge_base (required), active, description, +2 more.
create_change_requestC
Create a new change request.
Inputs: type (required), short_description (required), risk, impact, +6 more.
create_changesetC
Create a new changeset (update set).
Inputs: name (required), application (required), developer, description.
create_groupC
Create a new group, optionally with initial members.
Inputs: name (required), type, email, active, +4 more.
create_incidentC
Create a new incident.
Inputs: short_description (required), impact, urgency, category, +6 more.
create_knowledge_baseD
Create a new knowledge base.
Inputs: title (required), owner, managers, description, +2 more.
create_userC
Create a new user.
Inputs: email (required), last_name (required), user_name (required), first_name (required), +9 more.
get_articleB
Fetch a single knowledge article by sys_id.
Inputs: article_id (required).
get_catalog_itemA
Fetch a single catalog item by sys_id, including its variables (form fields).
Inputs: item_id (required).
get_change_request_detailsB
Fetch a single change request with its associated change tasks.
Inputs: change_id (required).
get_changeset_detailsA
Fetch a single changeset with the changes (sys_update_xml rows) it contains.
Inputs: changeset_id (required).
get_developer_work_reportA
Fetch developer work (sys_update_xml changes) between two dates, grouped by author and update set. Returns structured rows only — the caller (Claude) flags concerns narratively (e.g. changes in the Default update set, unnamed sets, unusually large sets, off-hours activity).
Inputs: end_date (required), start_date (required).
get_incident_by_numberA
Fetch a single incident by its number (e.g. INC0010001).
Inputs: incident_number (required).
get_optimization_recommendationsA
SIMULATED catalog optimization recommendations — low_usage/high_abandonment/slow_fulfillment stats are randomly fabricated (no real usage-tracking data source exists), matching the reference project's own use of Python's random module. inactive_items and description_quality reflect real instance data. Never present this as real analysis.
Inputs: recommendation_types (required), category_id.
get_syslog_reportA
Fetch sys_log rows (warnings/errors by default) for a given date, defaulting to yesterday. Returns raw rows only — the caller (Claude) does the 'suggested fixes' analysis in conversation.
Inputs: date, levels.
get_userA
Fetch a single user by sys_id, username, or email.
Inputs: email, user_id, user_name.
list_articlesA
List knowledge articles. limit/offset paginate — this returns one bounded page, not the full table.
Inputs: limit, query, offset, category, +2 more.
list_catalog_categoriesB
List service catalog categories. limit/offset paginate — this returns one bounded page, not the full table.
Inputs: limit, query, active, offset.
list_catalog_itemsC
List service catalog items. limit/offset paginate — this returns one bounded page, not the full table.
Inputs: limit, query, active, offset, +1 more.
list_catalog_item_variablesC
List the variables (form fields) defined on a catalog item.
Inputs: catalog_item_id (required), limit, offset.
list_categoriesB
List knowledge base categories. limit/offset paginate — this returns one bounded page, not the full table.
Inputs: limit, query, active, offset, +2 more.
list_change_requestsC
List change requests. limit/offset paginate — this returns one bounded page, not the full table.
Inputs: type, limit, query, state, +4 more.
list_changesetsB
List changesets (update sets). limit/offset paginate — this returns one bounded page, not the full table.
Inputs: limit, query, state, offset, +3 more.
list_groupsA
List groups. limit/offset paginate — this returns one bounded page, not the full table.
Inputs: type, limit, query, active, +1 more.
list_incidentsC
List incidents, most recent first. limit/offset paginate — this returns one bounded page, not the full table.
Inputs: limit, query, state, offset, +2 more.
list_knowledge_basesB
List knowledge bases. limit/offset paginate — this returns one bounded page, not the full table.
Inputs: limit, query, active, offset.
list_usersA
List users, most recent first. limit/offset paginate — this returns one bounded page, not the full table.
Inputs: limit, query, active, offset, +1 more.
move_catalog_itemsC
Move one or more catalog items to a different category.
Inputs: item_ids (required), target_category_id (required).
publish_articleA
Change a knowledge article's workflow state (defaults to published). NOTE: confirmed on this PDI that a direct field write silently reverts to draft — article state appears governed by the platform's own publish flow, not settable via a bare Table API write.
Inputs: article_id (required), workflow_state, workflow_version.
publish_changesetC
Publish a changeset. NOTE: requires a 'published' state choice to exist on sys_update_set — not present on every instance (confirmed absent on this PDI).
Inputs: changeset_id (required), publish_notes.
reject_changeA
Reject a change request's pending approval record and cancel the change. NOTE: may fail on instances with Change Model governance — confirmed on this PDI.
Inputs: change_id (required), rejection_reason (required), approver_id.
remove_group_membersB
Remove one or more members from a group.
Inputs: members (required), group_id (required).
resolve_incidentC
Resolve an incident (sets state to Resolved with a resolution code and notes).
Inputs: incident_id (required), resolution_code (required), resolution_notes (required).
submit_change_for_approvalA
Submit a change request for approval (sets state to Assess and creates an approval record). NOTE: may fail on instances with Change Model governance (state transition business rules) or where sysapproval_approver doesn't accept direct inserts — confirmed on this PDI.
Inputs: change_id (required), approval_comments.
update_articleC
Update an existing knowledge article.
Inputs: article_id (required), text, title, category, +2 more.
update_catalog_categoryC
Update an existing service catalog category.
Inputs: category_id (required), icon, order, title, +3 more.
update_catalog_itemC
Update an existing catalog item's core fields (name, description, category, price, active, order).
Inputs: item_id (required), name, order, price, +4 more.
update_catalog_item_variableC
Update an existing catalog item variable.
Inputs: variable_id (required), max, min, label, +7 more.
update_change_requestB
Update an existing change request (accepts sys_id or change number).
Inputs: change_id (required), risk, state, impact, +7 more.
update_changesetC
Update an existing changeset (accepts sys_id or name).
Inputs: changeset_id (required), name, state, developer, +1 more.
update_groupC
Update an existing group (accepts sys_id or name).
Inputs: group_id (required), name, type, email, +4 more.
update_incidentC
Update an existing incident (accepts sys_id or incident number).
Inputs: incident_id (required), state, impact, urgency, +10 more.
update_userC
Update an existing user (accepts sys_id, username, or email).
Inputs: user_id (required), email, phone, roles, +10 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 52 tools
Each tool targets a distinct resource and action. Even similar-sounding tools like create_catalog_category versus create_category are clearly separated by context in their descriptions. The report tools are also distinct from CRUD operations.
Tool names follow a consistent verb_noun pattern (e.g., list_incidents, create_incident, update_incident, get_incident_by_number). Minor deviations like create_category are still unambiguous due to domain context, and the overall style is uniform.
With 52 tools, the server is heavily overloaded, even though it covers multiple ServiceNow domains. This exceeds the 25-tool threshold for 'too many' and risks making tool selection more complex. While the breadth justifies a higher count, the sheer number is excessive for coherence.
The tool surface covers full CRUD and lifecycle operations for most domains: incidents, users, groups, changesets, catalog, knowledge, and change requests. Minor gaps exist (no delete operations for several resources, no incident approval workflow), but these are acceptable and do not hinder core workflows.
Maintenance
Related MCP Connectors
Read-only Trellus call reporting: call activity, rep results, sessions and call details.
Nori ERP reports: data dictionary, read-only SQL, saved reports and PDF print formats.
Query PanDev Metrics analytics and reporting data
Read-only NuMetric.work accounting & ERP data: statements, KPIs, reports, invoices, documents.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceProvides AI assistants with read access to ServiceNow instances to aid in building and debugging applications. It enables users to query tables, retrieve specific records, and inspect table schemas using standard ServiceNow encoded query strings.-
- AlicenseAqualityDmaintenanceA read-only MCP server that enables AI assistants to query ServiceNow instances—incidents, changes, users, CMDB—with malformed query linting and injection protection.7MIT
- FlicenseBqualityCmaintenanceEnables authenticated interaction with a ServiceNow Personal Developer Instance through OAuth 2.0, exposing tools to test connectivity and perform generic CRUD operations on any ServiceNow table plus flow management on the sys_hub_flow table.10-
- AlicenseAqualityBmaintenanceEnables agents to interact with a ServiceNow instance through thirteen consolidated tools covering records, schema, CMDB graph traversal, catalog, attachments, code, operations, knowledge, and administration, with a local store for notes, cache, saved queries, history, and revertible writes.13MIT