Server data from the Official MCP Registry
Governed ServiceNow MCP: per-profile table and field policy, dry-run batches, activity events.
About
Governed ServiceNow MCP: per-profile table and field policy, dry-run batches, activity events.
Security Report
This is a stdio ServiceNow MCP server with deny-by-default per-profile table policy, a confirm flag on destructive tools, dry-run batching, and credentials verified before they are saved. The main concerns are that the encryption key sits in the same owner-only directory as the encrypted profiles, and that write grants on privilege-sensitive tables are allowed with only a warning. Permissions (network to ServiceNow, local config files, spawning client CLIs) match the server's purpose, and the code excerpts show no exfiltration or obfuscation. Supply chain analysis found 6 known vulnerabilities in dependencies (0 critical, 1 high severity). Package verification found 1 issue.
4 files analyzed · 13 issues found
Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.
Permissions Required
This plugin requests these system permissions. Most are normal for its category.
What You'll Need
Set these up before or after installing:
How to Install
Add this to your MCP configuration file:
{
"mcpServers": {
"servicenow-mcp": {
"command": "npx",
"args": [
"-y",
"@onlyflows/servicenow-mcp@2.3.0"
],
"env": {
"SN_INSTANCE": "your-sn-instance-here",
"MCP_OWNER_ID": "your-mcp-owner-id-here",
"SN_AUTH_TYPE": "your-sn-auth-type-here",
"SN_CLIENT_ID": "your-sn-client-id-here",
"MCP_CLIENT_ID": "your-mcp-client-id-here",
"SN_PROFILE_NAME": "your-sn-profile-name-here",
"SN_ALLOWED_READ_TABLES": "your-sn-allowed-read-tables-here",
"SN_ALLOWED_WRITE_TABLES": "your-sn-allowed-write-tables-here",
"SN_TABLE_ACCESS_TARGETS": "your-sn-table-access-targets-here"
}
}
}
}Some servers take additional arguments. See the repository for details.
Documentation
View on GitHubFrom the project's GitHub README.
@onlyflows/servicenow-mcp
A governed ServiceNow MCP server: it lets an AI client read and change records on your instances, within limits you set per connection.
Built by OnlyFlows · Published by @onlyflowstech
Governed and safe for production
The server exposes 24 tools over stdio. Every call runs inside controls that you configure and that no tool of this server can change:
- Per-profile table and field policy. Each profile (a named ServiceNow connection) has its own read and write table allowlists. Access is deny-by-default: a profile with no rules denies every ServiceNow call. Field policy decides which fields can be read or written; sensitive field names are refused.
- Confirmation flag on destructive tools.
sn_deleteandsn_batchchange nothing unless the call carriesconfirm: true. The model sets that flag itself, so it is a guard against accidents, not an approval. A person approves through the client's own tool-approval prompt, and many clients let you "always allow" a tool.sn_createandsn_updatetake no confirm flag; keep write grants narrow. - Safe batching.
sn_batchtakes a structured filter (no raw encoded queries), runs as a dry run by default, caps a run at 10,000 records, and never re-sends a batch. - Activity events. Each completed tool call writes one JSON line to stderr with the tool, profile, instance and outcome, plus hashed owner and client labels. It records no table, record or fields. Delivery is best-effort through stderr, and events are dropped above 256 pending lines. Use ServiceNow's own audit history for record changes.
- Explicit profile on every call. There is no default or "active" instance. Each call names its profile, so nothing reaches an instance the call didn't name. Keep write grants on production profiles narrow.
- Credentials stay out of clients. Secrets are entered at a hidden prompt,
verified against the instance before anything is saved, and stored
encrypted in an owner-only
~/.servicenow-mcpdirectory.
Limits of these controls. They hold against the model's tool calls. A client that gives the model a shell or file access (Claude Code and Codex can) could run
servicenow-mcp-setup grantor read~/.servicenow-mcp/server.env. The encryption key sits in the same owner-only folder as the encrypted profiles, so it protects against other users and stray copies of the files, not against your own account. Run production profiles from a client or account without shell access where you can.
Details: Table access policy, Safety Features and docs/PRODUCTION-SECURITY.md.
Works with
Any MCP client that can launch a stdio server. Setup registers Claude Code
and Codex automatically; Claude Desktop, Cursor, VS Code and
Windsurf are configured with servicenow-mcp-setup client --client <name>
(see Connecting a client). Requires Node.js 20 or newer.
Quick start
- Install:
npm install -g @onlyflows/servicenow-mcp - Set up a connection:
servicenow-mcp-setup. It asks for your instance and credential, checks them against the instance, asks which tables to allow, and registers Claude Code and Codex if their CLIs are installed. The wizard's authentication type defaults to OAuth client credentials, so you can press Enter at that prompt. You need an Application Registry entry on the instance first: see OAuth 2.0. Basic is still offered, marked legacy, because ServiceNow is retiring it for REST calls. - Open your client and ask. There is no server to start; the client
launches
servicenow-mcpitself.
The default read grant in the wizard is just incident, and writes default
to none. Grant more later with servicenow-mcp-setup grant.
Try asking
These work with the default read grant (profile named dev):
- "On dev, list the 10 most recent open P1 incidents."
- "On dev, how many incidents are there, grouped by priority?"
- "On dev, which assignment groups have the most incidents?"
- "On dev, which open incidents have no assignee, oldest first?"
- "On dev, show incident INC0010001 and summarize where it stands."
Your client sends profile: "dev" with each call. Asking about other tables
(for example change_request) is denied until you grant them.
Installation
npm install -g @onlyflows/servicenow-mcp
servicenow-mcp-setup
Run bare on a terminal, servicenow-mcp-setup walks you through the whole
thing in one command: it generates the local auth material, asks for your
instance and credential, verifies that credential against the instance,
asks which tables to grant, writes the profile, and registers any supported
client whose CLI is installed. The credential is entered at a hidden prompt —
never an argument, never shell history — and nothing is written to the profile
until the instance has accepted it, so a typo or a wrong password leaves
nothing behind.
ServiceNow MCP setup
This walks through one ServiceNow connection end to end. Nothing is
written to the profile until your credential is verified against the
instance. Press Ctrl+C at any point to stop; nothing will be saved.
Profile name [dev]: dev
ServiceNow instance (for example dev12345.service-now.com): dev12345.service-now.com
Authentication:
1) oauth (default) - client credentials, recommended
2) apikey - inbound API key
3) basic - legacy, not recommended: ServiceNow is retiring it
Choice [1]: 1
OAuth client credentials need these on the instance:
- an Application Registry entry (System OAuth > Application Registry)
with a client ID and client secret
- the client credentials grant enabled for it
- an OAuth Application User: the integration user this server acts as,
with only the roles it needs, not an administrator
Steps: README, section Authentication > OAuth 2.0.
OAuth grant type:
1) client_credentials (default)
2) password
Choice [1]: 1
How should the credential be stored?:
1) encrypted (default)
2) reference
Choice [1]: 1
OAuth client id (not a secret): <your-client-id>
Enter each secret now. Input is hidden — nothing you type from here
is displayed.
clientSecret:
Verifying against the instance...
ok https://dev12345.service-now.com accepted the credential.
Table access is deny-by-default: a profile with no rules denies every
tool call. Grant the narrowest set that does the job; you can add more
later with servicenow-mcp-setup grant.
Tables to allow for READS:
1) Just incident (default)
2) Common ITSM set (incident,change_request,problem,task,sys_user)
3) All tables (*)
4) Enter a custom list
5) None
Choice [1]: 1
Tables to allow for WRITES:
1) Just incident
2) Common ITSM set (incident,change_request,problem,task,sys_user)
3) All tables (*)
4) Enter a custom list
5) None (default)
Choice [5]: 1
Wrote profile dev.
Register this server with codex and claude-code? [Y/n]: y
ServiceNow MCP doctor
ok node: v22.11.0
ok server command: servicenow-mcp resolves on PATH; clients spawn it over stdio
ok config directory: ~/.servicenow-mcp (0700)
ok profile dev: instance: https://dev12345.service-now.com
ok profile dev: credential: oauth clientSecret resolves from its encrypted source
ok profile dev: table access: 1 read, 1 write, 1 target(s)
All checks passed.
Setup complete.
Profile dev
Reads incident
Writes incident
Transport stdio (each client spawns its own servicenow-mcp)
Clients codex, claude-code
Start codex or claude-code and it will launch the server itself.
There is nothing to keep running between sessions.
There is nothing to start. The server speaks stdio: each registered client
spawns its own copy of servicenow-mcp on demand and talks to it over that
process's stdin and stdout. Setup finishes by running the same checks doctor
runs, so you can re-run them any time:
servicenow-mcp-setup doctor --profile dev
npx @onlyflows/servicenow-mcp@latest setup runs the same wizard without a
global install, and servicenow-mcp setup is an alias for
servicenow-mcp-setup.
If you choose Basic and the instance answers 401, the wizard explains the
Basic Auth restriction and asks what next: retry with the same settings,
switch to oauth (it discards the Basic credential and asks the OAuth
questions, keeping the profile name and instance), or stop. Nothing is
saved until a credential verifies.
Scripted setup
Pass any flag, or run without a terminal, and the wizard steps aside for the
original non-interactive behavior — so CI and provisioning scripts are
unaffected. --non-interactive forces it explicitly. Only the interactive
wizard defaults to OAuth. servicenow-mcp-profile create has no default you
should rely on: pass --auth-type oauth (recommended) or --auth-type basic.
Left out, it still creates a Basic profile, as it always has, so existing
scripts keep working, and it prints a deprecation notice only when standard
error is an interactive terminal, so output a script captures is unchanged. A
future release may require the flag.
servicenow-mcp-setup --non-interactive --clients none --json
servicenow-mcp-profile create --name dev --instance https://yourinstance.service-now.com \
--auth-type oauth --client-id <client-id> --source reference --provider env
servicenow-mcp-setup grant --profile dev --read incident,problem --write incident
The servicenow-mcp-setup commands
| Command | Purpose |
|---|---|
servicenow-mcp-setup | Generate local auth material and register supported clients |
servicenow-mcp-setup client --client <name> | Print copy-pasteable config for a client |
servicenow-mcp-setup grant --profile <name> --read <tables> | Add table access rules to a profile |
servicenow-mcp-setup policy show --profile <name> | Print the profile's effective policy as one table (tables, tools, fields, batch limits); never prints a secret |
servicenow-mcp-setup doctor | Diagnose the install and print remedies |
grant and the wizard print a warning, and still grant, when write access
lands on a privilege-sensitive table: role, group, approval, script,
property, user or authentication tables such as sys_user_has_role,
sysapproval_approver, sys_script or sp_widget, and the MID Server queue
(ecc_queue and its rotation shards), whose records can run commands on MID
Server hosts.
--force regenerates the owner/client identifiers but deliberately preserves
SN_PROFILE_ENCRYPTION_KEY, which decrypts every credential envelope in
config.json. Add --help to any command for its full options.
The server runs as you, and the client list is the boundary. Nothing listens on a port, so nothing off this machine can reach it and no web page can drive it. What that leaves is the registration: every MCP client registered here can spawn the server and use whatever ServiceNow access your profiles grant, as your integration account. Keep the grants narrow, and remove a client you no longer use with
claude mcp remove servicenow-mcporcodex mcp remove servicenow-mcp. No ServiceNow credential is copied into a client's configuration file — the spawned server reads the profile and its encryption key from the owner-only~/.servicenow-mcpdirectory.
Connecting a client
servicenow-mcp-setup registers Codex and Claude Code automatically when their
CLI is on PATH. For everything else:
servicenow-mcp-setup client --client claude-desktop
servicenow-mcp-setup client --client all
Every supported client speaks stdio natively, so each one is configured the same way: a command to spawn.
claude mcp add servicenow-mcp -- servicenow-mcp
codex mcp add servicenow-mcp -- servicenow-mcp
stdio is the default transport for both CLIs, so there is no transport flag to pass. For clients configured by file:
{
"mcpServers": {
"servicenow-mcp": { "command": "servicenow-mcp", "args": [] }
}
}
| Client | Configured by | Config location |
|---|---|---|
| Claude Code | claude mcp add or .mcp.json | project or --scope user |
| Codex | codex mcp add or config.toml | ~/.codex/config.toml |
| Cursor | file | ~/.cursor/mcp.json or .cursor/mcp.json |
| VS Code | file ("type": "stdio") | .vscode/mcp.json or user mcp.json |
| Claude Desktop | file | claude_desktop_config.json |
| Windsurf | file | ~/.codeium/windsurf/mcp_config.json |
No client holds a ServiceNow credential. The spawned server resolves its own
from ~/.servicenow-mcp, which is owner-only.
Full per-client blocks are in V2 service and client setup.
servicenow-mcpmust be on the spawning client'sPATH. A global npm install puts it there. If it is not — a project-local install, or a GUI client with a differentPATH— register the absolute entrypoint instead;servicenow-mcp-setup doctorchecks this and prints the exact command.
Guided profile creation from your client
After the bootstrap, a connected MCP client can walk you through profile creation:
Add a ServiceNow MCP profile for https://yourinstance.service-now.com
The MCP prompt is servicenow-mcp.add-profile. It guides profile naming, auth
mode, and least-privilege default-deny access, and deliberately does not
ask you to paste passwords, API keys, bearer tokens, OAuth client secrets, or
encryption keys into chat.
What gets installed
servicenow-mcp— the MCP server itself, spawned by a client over stdioservicenow-mcp-profile— manages profile credentials out of bandservicenow-mcp-setup— bootstrap, client config, grants, and diagnosis
Manual configuration without the bootstrap
The server keeps configuration explicit. A manual run needs:
- audit identity:
MCP_OWNER_IDandMCP_CLIENT_ID(optional; they label audit records and default tolocal-owner/local-client) - one named ServiceNow profile, either in
~/.servicenow-mcp/config.jsonor throughSN_PROFILE_NAME+SN_INSTANCE+ auth-specificSN_*variables - per-profile table access rules; unconfigured access denies everything
The SN_* environment path builds a profile only when
~/.servicenow-mcp/config.json does not exist. Once you create a profile
file, SN_ALLOWED_READ_TABLES, SN_ALLOWED_WRITE_TABLES, and
SN_TABLE_ACCESS_TARGETS stop applying and the rules must live on the profile
(servicenow-mcp-setup grant). This is the most common cause of a server that
denies every call; servicenow-mcp-setup doctor detects it.
The server reads ~/.servicenow-mcp/server.env itself at startup, because the
client that spawns it supplies its own environment and will not have sourced
anything. A value already present in the environment always wins over that
file, so container and CI configuration is unaffected.
For a quick environment-only run with no profile file — driving the server by hand over a pipe, or from a client that passes environment variables — inject protected values from your keychain or secret manager and pass only non-secret values on the command line:
MCP_OWNER_ID=local-owner \
MCP_CLIENT_ID=local-client \
SN_PROFILE_NAME=dev \
SN_INSTANCE=https://yourinstance.service-now.com \
SN_AUTH_TYPE=oauth \
SN_CLIENT_ID=your-non-secret-client-id \
SN_ALLOWED_READ_TABLES=incident,problem,change_request \
SN_ALLOWED_WRITE_TABLES=incident,change_request \
SN_TABLE_ACCESS_TARGETS='[{"table":"incident","kind":"canonical","tools":["sn_query","sn_get","sn_create","sn_update","sn_incident_add_comment","sn_incident_add_work_note","sn_delete","sn_batch"],"closureComplete":true,"relatedTables":["incident"]},{"table":"problem","kind":"canonical","tools":["sn_query","sn_get"],"closureComplete":true,"relatedTables":["problem"]},{"table":"change_request","kind":"canonical","tools":["sn_query","sn_get"],"closureComplete":true,"relatedTables":["change_request"]}]' \
servicenow-mcp
Do not put SN_PASSWORD, OAuth client secrets, or API keys in command history.
Inject them into the server's environment from your approved secret mechanism,
or leave them in the owner-only profile file where the server can resolve them
without any client seeing them.
Source install for development
Use source install only for development or unreleased changes:
git clone https://github.com/onlyflowstech/servicenow-mcp.git
cd servicenow-mcp
npm install
npm run build
npm start
For local development with a rebuild and source maps:
npm run dev
Container deployment applies to the dormant HTTP transport rather than a 2.0 stdio install; see Production container deployment and the enterprise boundary.
Multi-Instance Profiles
Manage multiple ServiceNow instances (dev, test, prod, PDI) with named profiles. Every tool call must select one configured profile explicitly; V2 has no active-profile or default-profile fallback.
Setup
Create profiles with the CLI rather than by hand — it captures credentials without putting them in argv, and it writes the file with the right ownership and mode:
servicenow-mcp-profile create --name dev --instance https://mydev.service-now.com --auth-type oauth --client-id <dev-client-id> --source reference --provider env
servicenow-mcp-profile create --name prod --instance https://myprod.service-now.com --auth-type oauth --client-id <prod-client-id> --source reference --provider env
servicenow-mcp-setup grant --profile dev --read incident,problem --write incident
servicenow-mcp-setup grant --profile prod --read incident
The resulting ~/.servicenow-mcp/config.json looks like this. Note
tableAccess: a profile without it denies every tool call.
{
"version": 2,
"profiles": {
"dev": {
"instance": "https://mydev.service-now.com",
"authType": "oauth",
"clientId": "your-dev-client-id",
"clientSecret": { "type": "secret_ref", "provider": "env", "reference": "SN_CLIENT_SECRET_DEV" },
"description": "Development instance",
"tableAccess": {
"readTables": ["incident", "problem"],
"writeTables": ["incident"],
"targets": [
{
"table": "incident",
"kind": "canonical",
"tools": [
"sn_query", "sn_get", "sn_aggregate", "sn_schema", "sn_codesearch",
"sn_create", "sn_update",
"sn_incident_add_comment", "sn_incident_add_work_note"
],
"closureComplete": true,
"relatedTables": ["incident"]
},
{
"table": "problem",
"kind": "canonical",
"tools": ["sn_query", "sn_get", "sn_aggregate", "sn_schema", "sn_codesearch"],
"closureComplete": true,
"relatedTables": ["problem"]
}
]
}
}
}
}
Have the approved supervisor, orchestrator, keychain, or secret manager provide
the values referenced by SN_CLIENT_SECRET_DEV and SN_CLIENT_SECRET_PROD in the
environment the server is spawned with, or in ~/.servicenow-mcp/server.env,
which the server falls back to. Do not type either value into a shell command,
command argument, dotenv file, or command history.
Each targets entry must set the literal closureComplete: true, and its
relatedTables must include the target table itself. relatedTables is a
declaration that the loader checks for consistency: every related table must
be in the allowlist of each operation the target is in, or the profile is
rejected. The loader does not derive it from the instance. ServiceNow returns
inherited fields through the child table's own endpoint, so a self-only list
such as ["incident"] is enough to read them. Declaring the immediate parent,
as servicenow-mcp-setup offers, is optional:
servicenow-mcp-setup grant --profile dev --read change_request --related change_request=task.
That adds task to the read allowlist, because the loader requires it, and a
later grant that gives change_request another operation adds task to that
operation's allowlist too. On its own this makes task addressable by no tool,
because it has no target of its own, unless such an allowlist is *. If
task has, or later gets, a target of its own, that target's tools can then
use those operations on it, so declare a table only where every tool on its
own target may use every operation the declaring target has or will have.
A grant on a base table such as task reaches the records of the tables that
extend it, such as incident, whatever relatedTables lists, so grant a base
table only when those records should be reachable through it. Likewise, a
view or alias returns data from every table it reads, whatever
relatedTables lists: declare each of those tables, so the loader requires
each to carry the same permission, and grant the view only when all of that
data should be reachable.
Credential Options
| Format | Example | Description |
|---|---|---|
| Legacy environment reference | "env:SN_PASSWORD_DEV" | Read-compatible V1 form; migrated to a structured reference on the next write |
| Secret reference | {"type":"secret_ref","provider":"env","reference":"SN_PASSWORD_DEV"} | Provider-neutral reference resolved only for the selected request |
| Encrypted envelope | {"type":"encrypted","version":1,...} | AES-256-GCM value created by the protected administration CLI |
Plaintext profile secrets are rejected. Use the installed servicenow-mcp-profile
operator command to create, inspect, rotate, or remove profiles; it reads secrets
through a protected prompt or bounded standard input and rejects credential-bearing
command-line arguments. Encrypted sources require exactly 32 random bytes encoded
as base64 or base64url in SN_PROFILE_ENCRYPTION_KEY, supplied separately by the
deployment secret mechanism and never stored in the profile file. See the
profile credential and administration guide.
The legacy env:VAR_NAME indirection remains readable for every secret field:
credential, clientSecret, and apiKey.
Using Profiles
Pass the profile parameter on every tool call:
- "query incidents on prod" — calls
sn_querywithprofile: "prod" - "get incident INC0010001 on dev" — calls
sn_getwithprofile: "dev" - "show me the dev profile endpoint" — calls the read-only
sn_profilediagnostic withprofile: "dev"
Profiles are created and changed out of band by the service operator. Legacy
default_profile metadata is ignored and is not persisted on the next
administrative write; the MCP boundary never consults it.
SN_* configuration compatibility
If no config file exists, canonical SN_* connection values are exposed only
through an explicit SN_PROFILE_NAME mapping. For example, set
SN_PROFILE_NAME=dev with SN_INSTANCE, SN_AUTH_TYPE=oauth, SN_CLIENT_ID
and SN_CLIENT_SECRET, then call tools with profile: "dev". Without
SN_AUTH_TYPE the environment profile is Basic (SN_USER and SN_PASSWORD),
as it has always been; set SN_AUTH_TYPE explicitly. Without SN_PROFILE_NAME, bare connection
variables create no profile and cannot route a request. Secret values remain
runtime-only environment references and are never persisted as plaintext.
Authentication
Three ServiceNow auth types are available per profile, selected with authType. The setup wizard and every example here use OAuth client credentials. A saved profile that has no authType is read as Basic, because that is what such a profile has always meant; saved profiles are never rewritten. Profile configuration is managed out of band by the service operator. This is the only authentication involved: the transport is stdio, so there is no endpoint in front of the server to protect.
Heads up: ServiceNow's inbound Basic Auth restriction program is phasing out basic auth for API requests — instances can start hard-rejecting it at any time (exemptions: Web-Service-Access-Only accounts or the
snc_basic_auth_api_accessrole). OAuth is the recommended auth type. The server prints a startup warning for basic-auth profiles.
OAuth 2.0 (recommended)
client_credentials grant (default). On the instance you need three things:
- An Application Registry entry, an OAuth API endpoint for external clients (System OAuth → Application Registry), which gives you a client ID and a client secret.
- The client credentials grant enabled for it: on current releases the system property
glide.oauth.inbound.client.credential.grant_type.enabledmust betrue. - An OAuth Application User set on that entry: the integration user the server acts as. Give it the least roles that do the job, not an administrator.
Then create the profile with the wizard (servicenow-mcp-setup, press Enter at the authentication prompt) or servicenow-mcp-profile create --auth-type oauth --client-id <client-id>, or reference the secret via env: indirection:
{
"version": 2,
"profiles": {
"dev": {
"instance": "https://mydev.service-now.com",
"authType": "oauth",
"clientId": "your-oauth-client-id",
"clientSecret": "env:SN_CLIENT_SECRET",
"description": "OAuth client_credentials"
}
}
}
password grant — set grantType and provide the user credentials as well:
{
"instance": "https://mydev.service-now.com",
"authType": "oauth",
"grantType": "password",
"clientId": "your-oauth-client-id",
"clientSecret": "env:SN_CLIENT_SECRET",
"username": "integration.user",
"credential": "env:SN_PASSWORD_DEV"
}
Tokens are cached until shortly before their expires_in expiry and refreshed automatically (including a single refresh + retry on 401). Token responses are never logged.
API key
For instances using Inbound Authentication Profiles with API keys. The header name is configurable (default x-sn-apikey):
{
"instance": "https://mydev.service-now.com",
"authType": "apikey",
"apiKey": "env:SN_API_KEY",
"apiKeyHeader": "x-sn-apikey"
}
Basic (legacy, deprecated by ServiceNow)
Basic is no longer the wizard's default. Use it only for an instance that still accepts it.
{
"instance": "https://mydev.service-now.com",
"username": "admin",
"credential": "env:SN_PASSWORD_DEV"
}
On a 401 for a basic-auth profile, the error explains the Basic Auth restriction program (KB3096078): the role snc_basic_auth_api_access or a Web-Service-Access-Only account is needed, and OAuth is the recommended way to move off Basic Auth. The setup wizard gives the same explanation when it verifies the credential.
Timeouts & retries
Every request is bounded by a timeout (default 30s; per-profile timeoutMs or env SN_TIMEOUT_MS) and retried up to twice with exponential backoff on 429/502/503/504, honoring Retry-After. POST requests are only retried on 429 — never after a 5xx that may have executed side effects.
ServiceNow upstream can return HTTP 429 with an empty body, while this server's own HTTP rate-limit rejections return a short JSON body plus Retry-After. Treat the status and Retry-After header as authoritative; do not benchmark or validate tool success from response latency or body shape alone. In normal ServiceNow instances, plan around the Background throttling default of roughly 120 requests per 60 seconds per identity unless the instance limit is explicitly raised.
What the tools cover
The registered catalog has 24 tools (see Tools Reference):
| Area | Tools |
|---|---|
| Records | sn_query, sn_get, sn_create, sn_update, sn_delete, sn_batch |
| Incident journals (append-only) | sn_incident_add_comment, sn_incident_add_work_note |
| Analytics and schema | sn_aggregate, sn_schema, sn_health |
| CMDB and operations | sn_relationships, sn_attach, sn_syslog, sn_codesearch, sn_discover |
| ATF | sn_atf_author, sn_atf_run, sn_atf_results, sn_atf_readiness, sn_atf |
| Flow Designer (read-only) | sn_flow_view |
| Profiles | sn_profile |
| Natural language | sn_nl (currently policy-denied pending a typed access plan) |
Every tool requires a profile, and every tool is subject to the profile's
table and field policy. sn_script (background scripts) is not registered; see
the Roadmap.
Manual environment setup
The server speaks stdio and requires Node.js 20 or newer. The shortest path is the bootstrap described under Installation:
servicenow-mcp-setup
That registers your clients; each one spawns the server when it needs it.
The rest of this section is the manual environment path, for a deployment that injects everything from a supervisor or secret manager, or for driving the server by hand over a pipe.
Use .env.example only as a non-secret configuration
inventory. Its protected-value assignments are intentionally empty; inject
ServiceNow secrets through a supervisor, orchestrator, keychain, or secret
manager rather than filling a repository dotenv file.
The
SN_ALLOWED_*andSN_PROFILE_NAMEvariables below build a profile only when~/.servicenow-mcp/config.jsondoes not exist. With a profile file present, put the rules on the profile withservicenow-mcp-setup grant.
export MCP_OWNER_ID="your-owner-id"
export MCP_CLIENT_ID="your-client-id"
export SN_ALLOWED_READ_TABLES="incident,problem,change_request"
export SN_ALLOWED_WRITE_TABLES="incident,change_request"
export SN_TABLE_ACCESS_TARGETS='[{"table":"incident","kind":"canonical","tools":["sn_query","sn_get","sn_create","sn_update","sn_incident_add_comment","sn_incident_add_work_note","sn_delete","sn_batch"],"closureComplete":true,"relatedTables":["incident"]},{"table":"problem","kind":"canonical","tools":["sn_query","sn_get"],"closureComplete":true,"relatedTables":["problem"]},{"table":"change_request","kind":"canonical","tools":["sn_query","sn_get"],"closureComplete":true,"relatedTables":["change_request"]}]'
export SN_PROFILE_NAME="dev"
export SN_INSTANCE="https://yourinstance.service-now.com"
export SN_AUTH_TYPE="oauth"
export SN_CLIENT_ID="your-non-secret-oauth-client-id"
npm run build
npm start
Before running those non-secret commands, the approved runtime secret mechanism must already have injected the authentication-specific ServiceNow secret into the process. Do not enter it in this shell block.
A client connects by spawning the command; there is no URL and no header:
{
"mcpServers": {
"servicenow-mcp": { "command": "servicenow-mcp", "args": [] }
}
}
JSON-RPC messages travel on the child's stdin and stdout, one newline-delimited message per frame. Everything else the server reports — startup warnings, and one structured JSON-line event per completed tool call — goes to stderr, which your client captures as its server log. There is no per-message size limit imposed by the transport.
For complete official SDK and independent client examples, safe two-profile setup, and crossed profile/result/audit checks, see V2 service and client setup.
Breaking changes in 2.0
Every tool call must name a profile, and table access is deny-by-default.
Those two require action on every install. The transport is stdio, as it was in
1.0.0, so a client configured with a command entry keeps working.
The breaking changes from 1.0.0, each with a before/after example, are in
Migrating to 2.0.
Already on 2.x? 2.2.0 changes field-policy loading and journal writes, and can refuse to start on a configuration that loads today. Read Upgrading to 2.2.0 first.
Deployment guides for the dormant HTTP transport
2.0 ships stdio only. The container image, the health and shutdown contract, the operations runbook, and the Secure MCP Tunnel adapter all describe the dormant HTTP transport, which no CLI path reaches. They are kept because that transport is a planned enterprise deployment shape, not because they apply to a 2.0 install — nothing in this section is needed to use this server.
- Production container deployment — OCI artifact, non-root runtime, provenance and scanning
- Remote operations runbook — health interpretation, telemetry, alerts, rotation, incident response
- Private ChatGPT connectivity — outbound-only Secure MCP Tunnel adapter
Tools Reference
Core CRUD
| Tool | Description |
|---|---|
sn_query | Query an approved table with structured filters, field selection, pagination, and sorting; bounded raw reads require an explicit policy rule. Paging runs on has_more and next_offset, which can end early if ServiceNow ACLs strip rows from a page; cross-check with sn_aggregate COUNT. A page cut to fit max_response_bytes keeps the same contract: see Paging when a response is cut to size |
sn_get | Get a single record by sys_id from an approved table |
sn_create | Create a record on any table granted for writes, using only field-policy-approved writable fields, including the journal fields comments and work_notes; incident additionally requires a bounded short_description |
sn_update | Update one record selected by exact sys_id on any table granted for writes, using only field-policy-approved writable fields; comments and work_notes append a journal entry |
sn_incident_add_comment | Append one bounded customer-visible comment to an incident; repeated calls append again |
sn_incident_add_work_note | Append one bounded internal work note to an incident; repeated calls append again |
sn_delete | Delete a record on an approved write table (requires confirm: true) |
sn_batch | Bulk update/delete using a required structured filter and dry-run safety (raw encoded selectors are prohibited; requires confirm: true to execute; a dry run returns the count, up to 5 sample records the profile may read, and the field names it would write). Values get the same policy as sn_update; execution uses the ServiceNow REST Batch API and never re-sends a batch |
Analytics & Schema
| Tool | Description |
|---|---|
sn_aggregate | COUNT, AVG, MIN, MAX, SUM with grouping |
sn_schema | Table field definitions, types, references |
sn_health | Instance version, cluster nodes, stuck jobs, key stats |
CMDB & Operations
| Tool | Description |
|---|---|
sn_relationships | CMDB CI graph traversal — upstream/downstream/both, configurable depth |
sn_attach | List attachments, return downloads as inline base64, and upload inline base64 content; never touches a host filesystem path |
sn_syslog | Query system logs with severity/source/time filters, newest first. tail: true starts a tail (the newest entries, oldest first, plus a cursor); each later call with after_cursor returns only the entries after it, oldest first, plus a new cursor (Tailing the system log) |
sn_codesearch | Search business rules, script includes, client scripts, etc., with a snippet around each match (Code search). Part of the default read grant, so a plain read grant on a code table allows it |
sn_discover | Discover tables, scoped apps, store apps, plugins |
Tailing the system log
sn_syslog can follow the log without re-reading it. The first call sends
tail: true and gets the newest limit entries (inside the since window),
oldest first, and a cursor. Each later call sends that cursor as
after_cursor and gets only the entries created after it, oldest first, and a
new cursor; poll no faster than every few seconds.
- No skips, no repeats. Many log rows share one
sys_created_onsecond, so the cursor holds the second and the row'ssys_id, and a call returns the rows after that pair. It is an opaque token: pass it back as given. has_more. If more thanlimitentries are waiting, the call returnslimitof them withhas_more: trueand a cursor at the last one; call again with it. A response cut to fit the byte budget does the same, and the cursor always names the last entry actually returned. Tail pages carry nototaland nonext_offset, andoffsetcannot be combined with a tail.- Same filters on every call. The cursor is bound to the
level,sourceandmessageit was issued for. A call that changes them is refused (so is a malformed, oversized or altered cursor) with a fixed message that does not repeat the cursor.sinceapplies to the first call only, but a cursor older than the longestsince(525,600 minutes, one year) is refused with a fixed message: start a new tail. With nothing to return, the call gives the same position back, so keep polling with it. If the first call finds no entries in its window it returns no cursor; call it again. - Reads go straight to the instance, never through the metadata cache, and
use the same table and field policy as an ordinary
sn_syslogread. A tail also readssys_idandsys_created_onto place the cursor, so a field policy that withholds either refuses it. - Limits. Order is by creation second, then
sys_id. A row the instance stores late with a creation time at or before the cursor's second is not seen by a tail that has already moved past it.
Testing & Automation
| Tool | Description |
|---|---|
sn_atf_author | Create tests/suites, ordered memberships and validated typed steps |
sn_atf | Legacy test/suite listing and results; execution redirects to sn_atf_run |
sn_atf_readiness | Check plugins, properties, Cloud Runner installation and permissions |
sn_atf_run | Execute a suite through Cloud Runner only, with bounded polling |
sn_atf_results | Fetch results, cached history and comparisons |
sn_nl | Currently fails closed until natural-language composition emits a complete typed access plan |
sn_script (background script execution) shipped in 1.0.0 as an unimplemented
stub and is not published in 2.0 — it does not appear in tools/list. Use
sn_query and sn_batch instead. See Roadmap.
Flow Designer
| Tool | Description |
|---|---|
sn_flow_view | Show a flow or subflow as a Mermaid diagram, an outline and a structured graph: trigger, steps, branches, loops, error handling, input values under field policy, and called subflows to depth 3. Read-only through the Table API; never calls Flow Designer's internal API. See docs/FLOW-VIEW.md |
Profile Management
| Tool | Description |
|---|---|
sn_profile | Inspect non-secret metadata and the effective policy card for one explicitly named profile; profile configuration is operator-managed out of band |
Documentation truncated — see the full README on GitHub.
Reviews
No reviews yet
Be the first to review this server!
More Business Tools MCP Servers
Toleno
Freeby Toleno · Developer Tools
Toleno Network MCP Server — Manage your Toleno mining account with Claude AI using natural language.
MCP Marketplace
Freeby mcp-marketplace · Developer Tools
Search and install MCP servers from inside your AI client.
mcp-creator-python
Freeby mcp-marketplace · Developer Tools
Create, build, and publish Python MCP servers to PyPI — conversationally.
by Lharries · Communication
Read, search, and send WhatsApp messages through your AI assistant
FinAgent
Freeby mcp-marketplace · Finance
Free stock data and market news for any MCP-compatible AI assistant.
Memory
Freeby Modelcontextprotocol · Productivity
Knowledge graph-based persistent memory across sessions
