Skip to main content
Glama
sn-mcp
by TaiRaven

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

3a30861

Original build: get_syslog_report + get_developer_work_report, stdio transport.

e4e6c68

Batch 0+1 of 8 — write CRUD layer (createRecord/updateRecord/deleteRecord) + Incident tools.

e450682

Batch 2 of 8 — User & Group tools.

63936c7

Batch 3 of 8 — Catalog tools.

34c08a9

Batch 4 of 8 — Change & Changeset tools.

873879d

Batch 5 of 8 — Knowledge Base tools.

0163165

Batch 6 of 8 — Story, Scrum Task & Project tools; epic tools dropped (see gap list below).

498ff17

Batch 7 of 8 — Script Include tools.

6a00bfc

Batch 8 of 8 (final) — classic Workflow tools; 3 tools dropped (see gap list below). Port complete: 76/82 reference tools shipped.

7a2fb41

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_epic is not a valid table on this PDI (confirmed via sys_db_object; this instance's Agile plugin install is scrum-only, no Epic/Project-portfolio linkage).

  • activate_workflow / deactivate_workflow — wf_workflow has no active field on this PDI at all (confirmed by dumping every element on the table).

  • reorder_workflow_activities — wf_activity has no order field 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

date

string

no

yesterday

YYYY-MM-DD

levels

string[]

no

["warning","error"]

Friendly names (trace/debug/info/warning/error/fatal), mapped internally to this instance's numeric syslog.level codes — see README §4 if pointing at a different instance.

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

start_date

string

yes

—

YYYY-MM-DD

end_date

string

yes

—

YYYY-MM-DD

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

servicenow

Official ServiceNow product docs, one index per release (~46k files each); pick with release

ServiceNowDocs/tools/build_index.py

https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/<branch>/<path>

moveworks

Mirror of docs.moveworks.com (~800 pages), optional

MoveworksDocs/tools/build_index.py

the live https://docs.moveworks.com/... page

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.

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

query

string

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 query section). Each hit carries match: phrase, all, some, or raw. Hyphens/colons are quoted for you.

source

"servicenow" | "moveworks" | "both"

no

"both"

both skips a source with no index and lists it under skipped.

release

string

no

SN_DOCS_BRANCH

ServiceNow release, e.g. australia or brazil. Ignored for Moveworks. An unconfigured release fails with the list of configured ones. Hits carry release.

limit

number

no

5

1–25, per source.

raw

boolean

no

false

Pass the query as literal FTS5 syntax (OR, NOT, "phrases", prefix*).

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

path

string

yes

—

e.g. markdown/<publication>/<file>.md.

source

"servicenow" | "moveworks"

no

try ServiceNow, then Moveworks

Pass the hit's source — both corpora use markdown/... paths.

release

string

no

SN_DOCS_BRANCH

ServiceNow only. Pass the hit's release — the same path usually exists in every release with different content.

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

source

"servicenow" | "moveworks"

no

"servicenow"

ServiceNow takes minutes (~46k files, needs SN_DOCS_REPO). Moveworks takes seconds (needs MW_DOCS_REPO); it re-indexes the local mirror only — run MoveworksDocs/tools/mirror.py first to pull new pages.

release

string

no

SN_DOCS_BRANCH

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 release — otherwise the call refuses rather than filling one release's index with another's docs. git checkout the branch in the ServiceNowDocs repo first.

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_incident

Create a new incident.

update_incident

Update an existing incident (accepts sys_id or incident number).

add_comment

Add a comment or work note to an incident.

resolve_incident

Resolve an incident (sets state to Resolved with a resolution code and notes).

list_incidents

List incidents, most recent first. One bounded page per call, not the full table.

get_incident_by_number

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_user

Create a new user.

update_user

Update an existing user (accepts sys_id, username, or email).

get_user

Fetch a single user by sys_id, username, or email.

list_users

List users, most recent first. One bounded page per call.

create_group

Create a new group, optionally with initial members.

update_group

Update an existing group (accepts sys_id or name).

add_group_members

Add one or more members to a group.

remove_group_members

Remove one or more members from a group.

list_groups

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_catalog_items

List service catalog items. One bounded page per call.

get_catalog_item

Fetch a single catalog item by sys_id, including its variables (form fields).

list_catalog_categories

List service catalog categories. One bounded page per call.

create_catalog_category

Create a new service catalog category.

update_catalog_category

Update an existing service catalog category.

move_catalog_items

Move one or more catalog items to a different category.

create_catalog_item_variable

Create a new variable (form field) on a catalog item.

list_catalog_item_variables

List the variables (form fields) defined on a catalog item.

update_catalog_item_variable

Update an existing catalog item variable.

get_optimization_recommendations

SIMULATED optimization recommendations — see note above.

update_catalog_item

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_change_request

Create a new change request.

update_change_request

Update an existing change request (accepts sys_id or change number).

list_change_requests

List change requests. One bounded page per call.

get_change_request_details

Fetch a single change request with its associated change tasks.

add_change_task

Add a task to a change request.

submit_change_for_approval

Submit for approval. NOTE: may fail — see gaps above.

approve_change

Approve a pending approval record and move to Implement. NOTE: may fail — see gaps above.

reject_change

Reject a pending approval record and cancel the change. NOTE: may fail — see gaps above.

list_changesets

List changesets (update sets). One bounded page per call.

get_changeset_details

Fetch a single changeset with the changes it contains.

create_changeset

Create a new changeset.

update_changeset

Update an existing changeset (accepts sys_id or name).

commit_changeset

Commit a changeset (sets state to complete).

publish_changeset

Publish a changeset. NOTE: may silently no-op — see gaps above.

add_file_to_changeset

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_knowledge_base

Create a new knowledge base.

list_knowledge_bases

List knowledge bases. One bounded page per call.

create_category

Create a new category in a knowledge base.

create_article

Create a new knowledge article.

update_article

Update an existing knowledge article.

publish_article

Change an article's workflow state. NOTE: silently reverts to draft — see note above.

list_articles

List knowledge articles. One bounded page per call.

get_article

Fetch a single knowledge article by sys_id.

list_categories

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_story

Create a new story.

update_story

Update an existing story (accepts sys_id or story number).

list_stories

List stories. One bounded page per call.

list_story_dependencies

List dependencies between stories.

create_story_dependency

Create a dependency between two stories.

delete_story_dependency

Delete a story dependency record.

create_scrum_task

Create a new scrum task under a story.

update_scrum_task

Update an existing scrum task (accepts sys_id or scrum task number).

list_scrum_tasks

List scrum tasks. One bounded page per call.

create_project

Create a new project.

update_project

Update an existing project (accepts sys_id or project number).

list_projects

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

List script includes (metadata only, not script bodies). One bounded page per call.

get_script_include

Fetch a single script include, including its full script body.

create_script_include

Create a new script include. WARNING: live executable code.

update_script_include

Update an existing script include. WARNING: live executable code.

delete_script_include

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_workflows

List classic Workflow definitions. One bounded page per call.

get_workflow_details

Fetch a single workflow definition, optionally including its versions.

list_workflow_versions

List the versions of a workflow.

get_workflow_activities

Fetch activities for a workflow version, defaulting to the latest published version.

create_workflow

Create a new (empty) workflow definition.

update_workflow

Update an existing workflow definition (accepts name or sys_id).

add_workflow_activity

Add an activity to a workflow version. See gap note above.

update_workflow_activity

Update an existing workflow activity's name or extra fields.

delete_workflow_activity

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

  1. All → Multi-Provider SSO → x509 Certificate (or the X.509 Certificates / sys_certificate table) → New → paste the contents of sn-mcp-public-cert.pem, Type PEM, Active = true.

  2. System OAuth → Application Registry → New → "Create an OAuth JWT API endpoint for external clients".

    • User Field: the sys_user field the JWT sub matches (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 jti each exchange).

    • Save, then record the auto-generated Client ID and Client Secret (or tick Public Client to skip the secret).

  3. On that endpoint → JWT Verifier Maps related list → New:

    • Kid: pick a value (e.g. sn-mcp) — this must equal SN_JWT_KID in .env.

    • Sys certificate: the cert record from step 1.

  4. Required claims (iss, aud, sub, exp) need no OAuth JWT Claim Validations records. aud and iss both default to the Client ID in this server; if your endpoint expects a different iss, add it as a claim validation and set SN_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 build

3. Verify auth before wiring into a client

With .env filled in and the project built:

npm run auth:test

It 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, not sys_log (sys_log returns 400 Invalid table sys_log).

  • syslog.level is numeric, not the strings "warning"/"error": -2=Trace, -1=Debug, 0=Information, 1=Warning, 2=Error, 3=Fatal (confirmed via GET /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'), not javascript: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.js

Use 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:http

Defaults: 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 existing useraccount auth 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 returns Grant 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 full admin (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_KID equals the endpoint's JWT Verifier Map Kid; the uploaded cert is the public half of SN_JWT_KEY_PATH and is Active; aud/iss = Client ID; and SN_JWT_SUBJECT matches a sys_user via the endpoint's User Field. Run npm 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 usually SNCRestrictBasicAuthUserAuthenticationGate — the "Web service access only" flag — which no longer applies to OAuth bearer tokens.)

  • Invalid table sys_log (HTTP 400) — the table is syslog, no underscore.

  • Report comes back empty even though logs exist for that day — level is numeric on this instance (see step 4), not the strings "warning"/"error". Re-check the mapping via the sys_choice query if pointing this at a different instance.

  • Missing SN_INSTANCE (or SN_CLIENT_ID, SN_JWT_KEY_PATH, ...) environment variables when launched as a real MCP server, even though .env exists and a direct node dist/index.js test from this folder works fine** — that direct test succeeds because its process.cwd() happens to be the project folder; Claude Code launches the server from elsewhere, so plain dotenv/config fails silently. Confirm src/index.ts resolves .env via import.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_report silently 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.ts used to build the date filter with sys_created_onBETWEENjavascript:gs.dateGenerate('<date>','00:00:00')@javascript:gs.dateGenerate(...). gs.dateGenerate() evaluates in the instance's configured timezone, but sys_created_on comes 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 the javascript: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_CLOSED in claude mcp list — the CLI session started before Node.js was on PATH. Register with node.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 /mcp in that session to reconnect; no restart needed.

Files

  • src/servicenow-client.ts — Table API wrapper (Basic Auth): queryTable/getRecord/createRecord/ updateRecord/deleteRecord, plus queryTableAll, 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 any list_* tool, which paginate one caller-controlled page at a time via plain queryTable. 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 ⚠ Truncated note 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 by user.ts and beyond) and buildTimeframeQuery (the upcoming/in-progress/completed filter shared by change.ts/story.ts/scrum-task.ts/ project.ts — deliberately built from a literal UTC timestamp, not javascript: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 an McpServer and 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 .env relative to itself (not cwd).

  • src/http.ts — Streamable HTTP entrypoint (step 7); bearer-token auth, one server+transport per session.

Available Tools

52 tools
add_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

    B3/5.0

    Scored across 52 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count2/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Provides 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.
      -
    • A
      license
      A
      quality
      D
      maintenance
      A read-only MCP server that enables AI assistants to query ServiceNow instances—incidents, changes, users, CMDB—with malformed query linting and injection protection.
      7
      MIT
    • F
      license
      B
      quality
      C
      maintenance
      Enables 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
      -
    • A
      license
      A
      quality
      B
      maintenance
      Enables 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.
      13
      MIT