接入你的智能体
發布者自己的指令。不是 PlugMCP 端點。
用我們的金鑰與日誌託管一份副本。
npx -y [email protected]Claude Code 沒有本機指令的安裝連結。複製下方指令並在終端機中執行。
SN_INSTANCE=<value> SN_AUTH=<value> SN_USER=<value> SN_PASSWORD=<secret> SN_API_KEY=<secret> SN_TOOL_PACKAGES=<value> claude mcp add io.github.leasstatt-servicenow-mcp-ai -- npx -y servicenow-mcp-ai@2.0.0在終端機中執行。
{ "mcpServers": { "io.github.leasstatt-servicenow-mcp-ai": { "command": "npx", "args": [ "-y", "[email protected]" ], "env": { "SN_INSTANCE": "<value>", "SN_AUTH": "<value>", "SN_USER": "<value>", "SN_PASSWORD": "<secret>", "SN_API_KEY": "<secret>", "SN_TOOL_PACKAGES": "<value>" } } }}claude_desktop_config.json
遠端 URL 還是本機指令? 兩種安裝方式的差異
來自發布者
ServiceNow MCP server — 67 tools over the full REST surface, every auth method, flows, diagrams.
A Model Context Protocol server that lets an MCP client (VS Code, Claude Desktop, etc.) run commands against a ServiceNow instance through its REST APIs — Table, Aggregate, Attachment, Import Set, Batch and CMDB, plus the Service Catalog, Change Management and Knowledge plugin APIs. Credentials are kept in a local env file and can be updated at runtime through a tool.
Upgrading from 2.x? 3.0 has breaking defaults (plan tokens for destructive applies, protected system tables, a smaller default tool set). Run
npx servicenow-mcp-ai migrate --writeonce: it carries your env file and MCP client config over and addsSN_COMPAT=2, which keeps every 2.x default you have not set. See the CHANGELOG → "Migration at a glance" for each change.
Upgrading from 1.x? v2.0 makes writes plan-by-default:
create/update/deleteand the other record-write tools return a non-mutating preview unless you passapply: true(or setSN_WRITE_MODE=applyto restore the v1 "execute immediately" behaviour). See the CHANGELOG → 2.0.0 for the full migration note.
Contents: Quick demo · Features · Requirements · Setup · Configure credentials · Run / debug · Develop · Tools · Resources · Prompts · Project structure · Security notes · Project documentation · Support
Built and maintained in my own time — if it helps, a GitHub Sponsors tip keeps it going. Full Support options are near the end.
Three things the platform makes hard, one call each. Point your MCP client at an instance (Setup) and ask:
1. "Where is this field actually used?" — every script, business rule, client script, UI policy/action and ACL that touches it, as JSON or a Mermaid graph. The IDE-grade find usages ServiceNow has no button for:
// servicenow_where_used
{
"kind": "field", // "table" | "field" | "script"
"name": "u_cost_center",
"mermaid": true, // also render a reference graph
}
2. "What runs when I save this record?" — the full automation chain in execution order (display → before → after → async business rules, then flows, workflows and notifications), each with its condition — a logical test that runs nothing:
// servicenow_trace_table_event
{
"table": "incident",
"operation": "update", // insert | update | delete | query
}
3. "What drifted between dev and prod?" — a Markdown diff of tables, columns, scripts (matched by sys_id then name, with a unified diff of every changed script) and plugins between two configured profiles — plus, on request, properties, choices, ACLs, notifications, flows, catalog items and roles — with a CI-friendly exit code so a pipeline can block a risky deploy:
servicenow-mcp-ai drift dev prod # report on stdout; exit 1 on drift, 0 if clean
All three are read-only and work against any instance — including a free PDI — with the model and client of your choice.
sys_db_object,
sys_dictionary).cmdb_rel_ci, IRE identify-and-reconcile with an identify-only
plan),
Service Catalog (browse/order items), Change Management (typed
creation + conflict detection) and Knowledge (article search).
Plugin-scoped APIs report clearly when not active on the instance.servicenow_search_code returns every matching line per artefact
(up to 20, with a line of context either side) and, like
servicenow_where_used, takes an optional application scope.
servicenow_where_used also finds structural references — dictionary
reference fields, list and form layouts, catalog variables, flow inputs and
reports — in a separate structural section.flows package — business rules, flows, workflows and
notifications, in order, with a Mermaid flowchart), read Flow Designer flows
and run history, explain Process Automation Designer playbooks
(servicenow_explain_flow with kind: "playbook" — lanes as Mermaid
subgraphs, activities, triggers, variants), and lint scripts against a local rule set with an aggregate
code-health report (codecheck; domains: true adds the flow, Service
Portal and legacy-workflow analysers). Run ATF tests via the CI/CD API (atf,
opt-in, non-default — the run tools execute on the instance).revert): list the local write journal and revert
one applied create/update/delete — with a drift check against later edits.artifacts, opt-in): list and read any
registered artifact type — UI policies with their actions, portal pages with
their layout, flows, catalog items and more — with scope and SDK-managed
status.updatesets, opt-in): list update sets, summarise
one set per artefact, compare it with another profile or a snapshot — and
bind applied Table writes to a named update set (update_set /
SN_UPDATE_SET), restoring the user's current set afterwards.ops, opt-in): bounded "why is it slow"
reads of the system log, the scheduler queue, the outbound email queue and
semaphores, plus servicenow_check_data_health — duplicate keys, orphaned and
stale references for one table, from Aggregate API counts.sys_audit and
sys_journal_field (history — including the comments and work notes the
Table API reads back empty), system properties with masked secrets and a
journaled, revertible set (properties), and user / group / role lookups
with memberships (directory). ATF runs can wait for their result
(wait_seconds), and Import Set inserts report the transform run and maps.SN_TOOL_PACKAGES
(default profile discovery; all enables everything).Retry-After, SSRF
guard, and a result-size guard.~/.config, or SN_ENV_FILE), updatable
at runtime via servicenow_set_credentials.engines + a runtime guard with a clear message;
the project targets the version in .nvmrc).From source (for development):
npm install
npm run build
Or run the published package directly, without cloning:
npx servicenow-mcp-ai
Every client launches the same stdio command, npx -y servicenow-mcp-ai (Node.js 22.12+),
under the server name servicenow. The one-click links and snippets below carry no
credentials: keep them in the env file (~/.config/servicenow-mcp-ai/.env, see
Configure credentials), run the one-time
npx servicenow-mcp-ai login for OAuth, or ask the assistant to call
servicenow_set_credentials once the server is connected. A real environment variable
set in a client config overrides the env file, so only add an env block when you
mean it — and never put SN_PASSWORD or other secrets into a client config you share
or commit (see SECURITY.md).
The zero-config route is the ServiceNow MCP extension from the Marketplace
(code --install-extension ivanbbaev.servicenow-mcp-ai); it registers the server in
Copilot Chat (agent mode) automatically, no mcp.json. Source: extension/.
Without the extension, add the server from a terminal (user profile):
code --add-mcp '{"name":"servicenow","command":"npx","args":["-y","servicenow-mcp-ai"]}'
code-insiders --add-mcp '{"name":"servicenow","command":"npx","args":["-y","servicenow-mcp-ai"]}'
The raw deeplinks behind the buttons (paste into a browser address bar):
vscode:mcp/install?%7B%22name%22%3A%22servicenow%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22servicenow-mcp-ai%22%5D%7D
vscode-insiders:mcp/install?%7B%22name%22%3A%22servicenow%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22servicenow-mcp-ai%22%5D%7D
Or a workspace file, .vscode/mcp.json:
{
"servers": {
"servicenow": {
"type": "stdio",
"command": "npx",
"args": ["-y", "servicenow-mcp-ai"]
}
}
}
Plugin (zero-config — installs the server wired up):
/plugin marketplace add IvanBBaev/servicenow-mcp-ai
/plugin install servicenow-mcp-ai
The plugin also ships eight workflow skills, two read-only subagents and three hooks — see Plugin skills.
CLI — --scope user makes it available in every project; --env sets a
non-secret variable (the instance host) and leaves the secrets in the env file. A value set
this way wins over the env file, so drop --env if you switch instances with
servicenow_set_credentials:
claude mcp add servicenow --scope user --env SN_INSTANCE=your-instance.service-now.com -- npx -y servicenow-mcp-ai
claude_desktop_config.json — macOS ~/Library/Application Support/Claude/, Windows
%APPDATA%\Claude\ (Settings → Developer → Edit Config):
{
"mcpServers": {
"servicenow": {
"command": "npx",
"args": ["-y", "servicenow-mcp-ai"]
}
}
}
Restart Claude Desktop after saving.
Use the button above, or open the deeplink directly:
cursor://anysphere.cursor-deeplink/mcp/install?name=servicenow&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsInNlcnZpY2Vub3ctbWNwLWFpIl19
Or edit ~/.cursor/mcp.json (global) / .cursor/mcp.json (project) with the same
mcpServers block as Claude Desktop.
All three take the Claude Desktop mcpServers block unchanged:
~/.codeium/windsurf/mcp_config.json (Cascade → MCP servers → View raw
config), then refresh the server list.cline_mcp_settings.json.{
"mcpServers": {
"servicenow": {
"command": "npx",
"args": ["-y", "servicenow-mcp-ai"]
}
}
}
In Zed's settings.json (Zed → Settings → Open Settings):
{
"context_servers": {
"servicenow": {
"source": "custom",
"command": "npx",
"args": ["-y", "servicenow-mcp-ai"],
"env": {}
}
}
}
~/.gemini/settings.json (user) or .gemini/settings.json (project):
{
"mcpServers": {
"servicenow": {
"command": "npx",
"args": ["-y", "servicenow-mcp-ai"]
}
}
}
Check it with /mcp inside a Gemini CLI session.
codex mcp add servicenow --env SN_INSTANCE=your-instance.service-now.com -- npx -y servicenow-mcp-ai
Or ~/.codex/config.toml:
[mcp_servers.servicenow]
command = "npx"
args = ["-y", "servicenow-mcp-ai"]
# Optional, non-secret only — secrets stay in ~/.config/servicenow-mcp-ai/.env:
# env = { SN_INSTANCE = "your-instance.service-now.com" }
Prefer a global install (npm install -g servicenow-mcp-ai)? Replace
"command": "npx", "args": ["-y", "servicenow-mcp-ai"] with
"command": "servicenow-mcp-ai" in any snippet. The
MCP Inspector works the same way:
npx @modelcontextprotocol/inspector npx -y servicenow-mcp-ai.
The one-click links are generated from package.json by scripts/install-links.mjs
(node scripts/install-links.mjs prints them); test/install-links.test.js fails if
this README or the docs site drift from the generated strings.
An MCP bundle is one .mcpb file with the
server and its dependencies; Claude Desktop (or any MCPB host) installs it in one click, with
no npm / npx. Its form asks for the connection keys (only SN_INSTANCE is required) and
SN_TOOL_PACKAGES; secrets are marked sensitive (kept in the OS keychain). An empty field
falls back to the env file. Not published yet (O-22) — build it with npm run mcpb:pack
(dist/mcpb/; -- --validate runs the official validator).
The repository ships a multi-stage Dockerfile (distroless Node 22 runtime, non-root
uid 65532). The image contains exactly what npm pack publishes plus production
dependencies, and starts the HTTP transport on 0.0.0.0:3000 by default. No image
is published to a registry yet — build it locally:
docker build -t servicenow-mcp-ai .
# Secrets as files (Docker / Kubernetes secrets), mounted read-only
mkdir -p secrets && printf '%s' 'your-password' > secrets/sn_password
openssl rand -hex 32 > secrets/sn_http_token
docker run --rm -p 127.0.0.1:3000:3000 \
-e SN_INSTANCE=your-instance.service-now.com -e SN_USER=your.user \
-e SN_PASSWORD_FILE=/run/secrets/sn_password \
-e SN_HTTP_TOKEN_FILE=/run/secrets/sn_http_token \
-v "$PWD/secrets:/run/secrets:ro" -v sn-data:/data \
servicenow-mcp-ai
SN_HTTP_TOKEN is required for any non-loopback bind. The image binds 0.0.0.0
so the published port works; without a token (or OAuth) the server refuses to start
(3.0, B6). SN_HTTP_REQUIRE_TOKEN=0 lets it start with a warning, and then every
client that reaches the port drives your instance with the configured credentials.
Clients send Authorization: Bearer <token>; terminate TLS in front of the container.SN_HTTP_OAUTH_ISSUER (your OIDC
provider) and SN_HTTP_OAUTH_RESOURCE (this server's public URL, e.g.
https://mcp.example.com/mcp). Clients discover the issuer from
/.well-known/oauth-protected-resource and send its JWT access tokens; the token must
name the resource as its audience. Optional: SN_HTTP_OAUTH_SCOPES,
SN_HTTP_OAUTH_AUDIENCE, SN_HTTP_OAUTH_JWKS_URI. For an issuer that hands out opaque
tokens, set SN_HTTP_OAUTH_INTROSPECTION_URI plus its client id and secret (RFC 7662). By
default the instance is still called with the configured service account.SN_HTTP_OAUTH_USER_TOKENS=true, a
32-byte SN_HTTP_OAUTH_TOKEN_KEY (base64 or hex, e.g. openssl rand -base64 32) and an
OAuth client on the instance (SN_OAUTH_CLIENT_ID / SN_OAUTH_CLIENT_SECRET, refresh
tokens enabled) whose redirect URL is /oauth/servicenow/callback on the
SN_HTTP_OAUTH_RESOURCE origin. The first call from a user returns a link to the
instance's sign-in page (URL elicitation; a 2025 session gets -32042, a client without
URL elicitation and a background task get an error carrying the link). After
the user signs in, the server checks that the account's sys_user field matches the
token's claim (SN_HTTP_OAUTH_USER_MATCH, default email=email), keeps the refresh token
AES-256-GCM encrypted in SN_HTTP_OAUTH_TOKEN_STORE, and from then on calls the instance as
that user, so ServiceNow ACLs apply per user. A user drops their own links with
DELETE /oauth/servicenow/link (their bearer token; answers { unlinked, revoked }); the
refresh tokens are also revoked on the instance, best effort. Replicas behind one
SN_HTTP_OAUTH_RESOURCE can each complete a link when they share SN_HTTP_OAUTH_TOKEN_KEY
and the store. Limit: requests authorized with SN_HTTP_TOKEN still use the shared
credential./data holds the docs directory (SN_DOCS_DIR=/data/docs) and the env file
(SN_ENV_FILE=/data/.env); mount a volume there to keep them.<KEY>_FILE secret source is described in Secrets from files.-i -e SN_TRANSPORT=stdio
(docker run --rm -i -e SN_TRANSPORT=stdio -e SN_INSTANCE=… servicenow-mcp-ai).HEALTHCHECK is a TCP liveness probe. GET /healthz (liveness) and GET /readyz
(credentials configured) answer without the token for orchestrator probes;
GET /readyz?probe=1 also calls the instance and sits behind the token, like every
MCP route. Set SN_HTTP_ALLOWED_HOSTS to the name clients use so the Host header is
checked on a 0.0.0.0 bind.smithery.yaml describes the same image for Smithery (stdio,
config keys mapped to the SN_* settings).With SN_TRANSPORT=http every MCP session (one initialize) gets its own server:
servicenow_use_instance is session-scoped over HTTP. It switches the profile of
the calling session only; other sessions keep theirs and nothing is written. Pass
persist: true to also write SN_ACTIVE_PROFILE to the env file (journaled) — that
changes the default for sessions that have not switched. Over stdio the switch lasts
until the process exits; persist: true writes it there too (3.0, B12).DELETE or after SN_HTTP_SESSION_TTL_SEC idle
(default 30 min); a request with an ended session id gets 404 and the client
re-initializes. At most SN_HTTP_MAX_SESSIONS (64) are open at once.Host header must match SN_HTTP_ALLOWED_HOSTS
(default: the loopback names on a loopback bind) and a browser Origin must match
SN_HTTP_ALLOWED_ORIGINS (default: loopback origins); otherwise 403.GET /healthz → 200 {"status":"ok"} while serving. GET /readyz →
200 when credentials are configured, 503 otherwise. Both answer without the token.
GET /readyz?probe=1 (behind the token) also reads one sys_user row and returns
503 when the instance is unreachable; the result is cached for 5 s.SN_HTTP_KEEPALIVE_MS (25 s).The fastest path is three lines of Basic auth — set these (in the env file or the real environment) and you are connected:
SN_INSTANCE=dev12345.service-now.com
SN_USER=your.username
SN_PASSWORD=your-password
Everything else is optional tuning; see the full Environment variables reference for the rest.
Past a quick try, prefer OAuth over a stored password. For anything shared or long-lived, run the one-time
npx servicenow-mcp-ai logininstead — it stores a refresh token, not your password. See Configure credentials → OAuth 2.1.
Once the three variables are set, confirm the connection before you start:
servicenow_test_connection tool — it reads one sys_user record and
reports ok, HTTP status and latency.servicenow_check_capabilities — it previews which admin-restricted sys_*
tables the connected user can actually read.Or do both from the shell in one shot:
npx servicenow-mcp-ai doctor # checks credentials, reachability and capabilities
Prefer to be asked? npx servicenow-mcp-ai init prompts for the instance, the
auth method and the credentials, writes the env file and runs doctor — see
Command-line interface.
Credentials live in ~/.config/servicenow-mcp-ai/.env (or the file SN_ENV_FILE names):
SN_INSTANCE=your-instance.service-now.com
[email protected]
SN_PASSWORD=your-password
SN_INSTANCE accepts dev12345, dev12345.service-now.com or a full https:// URL.
You can also set or change them at runtime by calling the
servicenow_set_credentials tool — the new values are written straight back to the env file.
Moving a configured profile to a different instance requires user and password in the same
call (the stored secrets are never sent to another host), and the change must be confirmed by
the client — clients without elicitation support are refused unless
SN_ALLOW_UNCONFIRMED_CREDENTIAL_CHANGE=1 is set.
The tool also sets the auth method (auth), the OAuth client id (oauth_client_id) and grant
(oauth_grant). Secrets — the API key and the OAuth client secret — are never tool arguments:
list them in request_secrets and the server asks for them through an elicitation prompt, so
they never appear in a logged tool call, the result or the write journal. A client without
elicitation support is refused (the opt-out above does not apply to secrets); set those keys in
the env file instead. The instance-change rule follows the resulting auth method: an API-key
profile needs a new API key, an OAuth client_credentials profile a new client secret, the
OAuth password grant user, password and client secret, Basic / none user and password;
bearer-token, refresh_token and jwt_bearer profiles cannot be moved with this tool.
servicenow_get_status (authWarnings), servicenow_list_instances and doctor evaluate each
profile against its own auth method — an API-key profile needs no password — and report the
method, the OAuth grant, the refresh-token state and the write mode, never a secret value. When
the refresh-token grant returns a rotated refresh token, it is written back to the env key it
was read from; if the env file cannot be written, the new token is kept in memory (lost on
restart) and a warning is logged and shown by get_status / doctor. Values the server writes
keep Windows paths literal (backslashes are single-quoted) and a CRLF env file stays CRLF. On
Windows the env file inherits its folder's ACL — restrict it yourself (for example
icacls .env /inheritance:r /grant:r "%USERNAME%:F"); the server only warns, it never runs
icacls.
The env file is resolved in this order: SN_ENV_FILE, then
~/.config/servicenow-mcp-ai/.env (XDG). A project-root .env is deprecated (3.0, B5):
if one exists while neither of the two is in use, it is still read and startup warns where to move it.
A global/npx install therefore writes to your user config rather than into
node_modules. Real environment variables always take precedence over the file.
At initialize the server sends instructions built from the live configuration: the enabled
packages and tool count, the write mode, the active profile and, when nothing is configured,
what is missing and how to fix it — plus pointers to the prompts, the reference resources
and large-result handling (paging, format "file"). Until then every instance tool fails with
code: "NOT_CONFIGURED" and a hint naming servicenow_set_credentials. A first session
with an empty env file looks like this (abridged):
instructions Credentials: NOT configured (missing instance, user, password). Instance tools
fail with code NOT_CONFIGURED until fixed. To configure: ask the user for
the instance and credentials, call servicenow_set_credentials, then
servicenow_test_connection. Never guess or echo a password.
user How many open P1 incidents do we have?
model Which instance, user and password should I connect with?
user dev12345, admin, ••••••
tool call servicenow_set_credentials { instance: "dev12345", user: "admin", password: … }
tool result { message: "Credentials saved", profile: "default", configured: true, password: "***" }
tool call servicenow_test_connection {}
tool result { ok: true, … }
tool call servicenow_aggregate { table: "incident", query: "active=true^priority=1" }
model There are 7 open P1 incidents.
servicenow_get_status then shows the live state: server version, uptime and transport,
policy.summary, limits, redaction, the docs directory, write counters, the profile source and
profileDetails (per-profile auth mode, write mode and missing keys) — never a secret value.
Register an Authorization Code OAuth API endpoint in ServiceNow with a
loopback redirect URL (e.g. http://localhost:53682/callback), set
SN_OAUTH_CLIENT_ID (and SN_OAUTH_CLIENT_SECRET for a confidential client),
then run the one-time interactive login:
npx servicenow-mcp-ai login
It opens the browser, you approve, and the obtained refresh token is stored in your env file. The server then runs non-interactively (refresh_token grant) — no password is ever stored. PKCE (S256) is always used.
The OAuth 2.0 password grant (ROPC) is deprecated in OAuth 2.1 and disabled on many instances; prefer
login.client_credentialsandrefresh_tokengrants remain supported for service accounts. See .env.example.
Every inbound REST auth method ServiceNow offers is covered:
All settings are read from the env file (SN_ENV_FILE, else
~/.config/servicenow-mcp-ai/.env) or the real process environment, which takes
precedence. Only the first three are required; the rest are optional tuning knobs.
See .env.example for a template. Every value is validated at
startup: an invalid one stops the server with an error that names every offending key
(3.0, B5), or — with SN_STRICT_SETTINGS=0 — is logged as a warning and the setting keeps
its default.
These tables are generated from the settings manifest
(src/core/settings-manifest.ts) — edit the manifest, then run
npm run docs:env.
The instance and its credentials. Only SN_INSTANCE is always required; the auth method is auto-detected from the keys present (API key -> bearer token -> OAuth -> Basic) unless SN_AUTH names it.
Container secrets (D-5): FILE=/path loads from that file at startup (one trailing newline is trimmed). Setting both and FILE is a startup error; so is an unreadable or empty file. A value loaded this way is never written back to the env file. Per profile: SN_PROFILE_FILE for the ServiceNow secrets.
The bare SN_INSTANCE / SN_USER / SN_PASSWORD keys are the 'default' profile. More instances live under SN_PROFILE__* keys; switch with SN_ACTIVE_PROFILE or the servicenow_use_instance tool.
Timeouts, retries, the host allow-list, the outbound proxy, mutual TLS and the per-host queue and circuit breaker. They govern every REST client of the server. The proxy and mutual TLS need the optional undici package.
Which tools are registered. The admin tools (set_credentials, get_status, use_instance) are always on.
Least-privilege table policy, plan-and-apply writes, destructive-write confirmation, per-session caps, prod profiles, update-set binding and the upload / email / SDK-managed-scope guards.
Result size budgets, output shaping, redaction of record values, the write journal and CSV export safety.
The schema reads cache and the capability / plugin-API probes.
The local Markdown docs store (also home of the write journal — keep it out of version control) and the generated Mermaid diagrams.
stdio (default, one local client) or Streamable HTTP for remote and agent clients. Securing the HTTP endpoint (TLS, auth, network) is the operator's job.
The stderr log, the optional log file and the log lines mirrored to the MCP client.
Every setting is validated at startup. An invalid safety value is a startup error; an invalid tuning value is logged as a warning and the setting keeps its default (see SN_STRICT_SETTINGS).
Conventional variables outside the SN_ namespace that the server also honours.
Every secret setting can be read from a file, the convention of Docker, Compose / Swarm and Kubernetes secrets: set <KEY>_FILE to a path and the server loads <KEY> from it at startup. This covers SN_PASSWORD, SN_API_KEY, SN_BEARER_TOKEN, SN_OAUTH_CLIENT_SECRET, SN_OAUTH_REFRESH_TOKEN and SN_HTTP_TOKEN, plus the per-profile forms (SN_PROFILE_PROD_PASSWORD_FILE, SN_PROFILE_PROD_API_KEY_FILE, …).
echo secret > file works; other whitespace is kept.<KEY> and <KEY>_FILE is a startup error that names the pair — the server never picks one silently.servicenow_set_credentials and OAuth refresh-token rotation refuse to persist it (a rotated refresh token stays in memory with a warning) — update the file.SN_TOKEN_FILE (bearer token re-read on a 401), SN_OAUTH_JWT_KEY_FILE and the SN_TLS_*_FILE PEM paths are paths the server reads itself, not <KEY>_FILE sources.Access is controlled on two independent axes: tables and tool packages.
Since H-4 the plugin-backed tools (Change, Catalog, Knowledge, Email, ATF) and attachments (through the parent record's table) obey the table axis too; the package axis still removes whole surfaces. See Security notes for the full model (including how the Batch API obeys both axes).
List syntax: table lists (SN_TABLES_ALLOW / SN_TABLES_DENY) are
comma-separated; package lists (SN_TOOL_PACKAGES, SN_PACKAGES_DENY,
SN_PACKAGES_READONLY) accept commas or whitespace. Surrounding spaces are
trimmed in both, and table matching is case-insensitive — so
SN_TABLES_DENY=Change_Request, sys_user works. Since H-11 a table entry may be
a pattern (* any run, ? one character): SN_TABLES_DENY=sys_* blocks
sys_user and leaves incident alone. The order is: an exact deny, an exact
allow, a pattern deny, the protected tables (writes; since 3.0 they need the
call's own apply: true — SN_PROTECTED_TABLES_WRITE=confirm; deny refuses
them, allow lifts the rule), then the allowlist's
patterns. Ask
servicenow_explain_policy({table, action}) which rule decides, or read
servicenow://policy.
npm run inspectornpm startStatus. servicenow_get_status carries an observability block: per-tool
{count, errors, p50, p95, totalMs} (percentiles in ms over each tool's last 256
calls — memory stays bounded) plus result sizes {bytesTotal, textBytes, structuredBytes, bytesP50, bytesP95} (UTF-8 bytes of the text blocks and of
structuredContent, the wire cost of each tool), schema-cache hits/misses, per-host retry counters,
queue limits and occupancy, circuit-breaker state and the last X-RateLimit-*
headers each host sent. It never calls the instance.
Logs. Logs go to stderr only (stdout is the MCP protocol). SN_LOG_FORMAT=text
switches from JSON lines to a human-readable format; SN_LOG_FILE also appends
JSON lines to a size-rotated file. Credential-named fields (password, token,
authorization, …) are masked in every sink, and the SN_REDACT_FIELDS /
SN_REDACT_PII rules and the secret-column masking apply on top.
Tracing hooks. Every tool call and the request loop publish on
node:diagnostics_channel, so an
OpenTelemetry (or any) subscriber can attach without a dependency on this server.
Messages are built only while a channel has a subscriber:
url never includes the query string; headers, bodies and credentials are never
published, and errorMessage passes through the redaction rules.
Tool arguments and results are never published (only the result's byte count).
callId on an HTTP message is the id of the tool call that made it.
traceparent / tracestate are the W3C Trace Context the client sent in the call's
params._meta; a malformed value is dropped.
OpenTelemetry spans. SN_OTEL=1 maps those channels to spans through
@opentelemetry/api, an optional
peer dependency (npm install @opentelemetry/api next to the server, plus your SDK
and exporter registered with node --import). Without the package the server logs one
warning and runs without spans; with SN_OTEL off the package is never loaded.
SERVER span named tools/call <tool>, a child of the client's
traceparent when it sent one. Attributes: mcp.method.name,
gen_ai.operation.name (execute_tool), gen_ai.tool.name, jsonrpc.request.id,
mcp.session.id, network.transport, error.type, plus servicenow_mcp.package
/ .profile / .outcome / .result.bytes.CLIENT span named after the method, a child of its tool
span: http.request.method, server.address, url.full (no query string),
http.response.status_code, http.request.resend_count, error.type, and one
retry event per replay.SN_OTEL_PROPAGATE=1 (off by default) also sends traceparent / tracestate
headers on requests to the ServiceNow instance: the HTTP span's context when
SN_OTEL is on, otherwise the client's context unchanged. It is opt-in because it
hands trace ids to the instance; the OAuth token endpoint never gets them.Prometheus. With the HTTP transport, SN_METRICS=1 and SN_HTTP_TOKEN set,
GET /metrics (same bearer token) serves the same figures in the Prometheus text
format (servicenow_mcp_* families, labelled by tool / host only). Without a
token the endpoint stays off and a warning is logged.
The published servicenow-mcp-ai binary (run it directly, or via
npx servicenow-mcp-ai) starts the MCP server when it is given no command, and
otherwise runs one of the commands below and exits. Connection settings come from
environment variables / the env file (see Environment variables).
servicenow-mcp-ai --help lists everything; --version prints the version. An
unknown command or option prints the usage on stderr and exits 2 — it never
starts the server.
| Command | Options | What it does | Exit codes
ServiceNow MCP server — 67 tools over the full REST surface, every auth method, flows, diagrams.
{ "mcpServers": { "io.github.leasstatt-servicenow-mcp-ai": { "command": "npx", "args": [ "-y", "[email protected]" ], "env": { "SN_INSTANCE": "<value>", "SN_AUTH": "<value>", "SN_USER": "<value>", "SN_PASSWORD": "<secret>", "SN_API_KEY": "<secret>", "SN_TOOL_PACKAGES": "<value>" } } }}工具
尚無工具清單。遠端伺服器會在首次健康檢查後取得工具清單。
常見問題
在本頁複製適用於 Cursor、Claude Desktop、Claude Code 或 VS Code 的 stdio 設定。它使用發布者的安裝方式,而不是 PlugMCP 代理伺服器。
發布者列出了以下環境變數:SN_INSTANCE, SN_AUTH, SN_USER, SN_PASSWORD, SN_API_KEY, SN_TOOL_PACKAGES。
Servicenow MCP Ai 透過 stdio 在本機執行。
上次檢查時間:2026-11-09。 ServiceNow MCP server — 67 tools over the full REST surface, every auth method, flows, diagrams.