Back to Browse

Servicenow MCP Server

Business ToolsUse Caution4.8MCP RegistryLocal
Free

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

4.8
Use Caution4.8High Risk

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.

HTTP Network Access

Connects to external APIs or services over the internet.

File System Read

Reads files on your machine. Normal for tools that analyze or process local data.

File System Write

Writes or modifies files on your machine. Check that this is expected for the tool.

env_vars

Check that this permission is expected for this type of plugin.

process_spawn

Check that this permission is expected for this type of plugin.

What You'll Need

Set these up before or after installing:

MCP_OWNER_IDRequired
MCP_CLIENT_IDRequired
SN_ALLOWED_READ_TABLESRequired
SN_ALLOWED_WRITE_TABLESRequired
SN_TABLE_ACCESS_TARGETSRequired
SN_PROFILE_NAMERequired
SN_INSTANCERequired
SN_AUTH_TYPERequired
SN_CLIENT_IDRequired

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 GitHub

From 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.

npm version License: MIT

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_delete and sn_batch change nothing unless the call carries confirm: 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_create and sn_update take no confirm flag; keep write grants narrow.
  • Safe batching. sn_batch takes 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-mcp directory.

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 grant or 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

  1. Install: npm install -g @onlyflows/servicenow-mcp
  2. 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.
  3. Open your client and ask. There is no server to start; the client launches servicenow-mcp itself.

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):

  1. "On dev, list the 10 most recent open P1 incidents."
  2. "On dev, how many incidents are there, grouped by priority?"
  3. "On dev, which assignment groups have the most incidents?"
  4. "On dev, which open incidents have no assignee, oldest first?"
  5. "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

CommandPurpose
servicenow-mcp-setupGenerate 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 doctorDiagnose 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-mcp or codex 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-mcp directory.

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": [] }
  }
}
ClientConfigured byConfig location
Claude Codeclaude mcp add or .mcp.jsonproject or --scope user
Codexcodex mcp add or config.toml~/.codex/config.toml
Cursorfile~/.cursor/mcp.json or .cursor/mcp.json
VS Codefile ("type": "stdio").vscode/mcp.json or user mcp.json
Claude Desktopfileclaude_desktop_config.json
Windsurffile~/.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-mcp must be on the spawning client's PATH. A global npm install puts it there. If it is not — a project-local install, or a GUI client with a different PATH — register the absolute entrypoint instead; servicenow-mcp-setup doctor checks 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 stdio
  • servicenow-mcp-profile — manages profile credentials out of band
  • servicenow-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_ID and MCP_CLIENT_ID (optional; they label audit records and default to local-owner/local-client)
  • one named ServiceNow profile, either in ~/.servicenow-mcp/config.json or through SN_PROFILE_NAME + SN_INSTANCE + auth-specific SN_* 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

FormatExampleDescription
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_query with profile: "prod"
  • "get incident INC0010001 on dev" — calls sn_get with profile: "dev"
  • "show me the dev profile endpoint" — calls the read-only sn_profile diagnostic with profile: "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_access role). 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:

  1. 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.
  2. The client credentials grant enabled for it: on current releases the system property glide.oauth.inbound.client.credential.grant_type.enabled must be true.
  3. 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):

AreaTools
Recordssn_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 schemasn_aggregate, sn_schema, sn_health
CMDB and operationssn_relationships, sn_attach, sn_syslog, sn_codesearch, sn_discover
ATFsn_atf_author, sn_atf_run, sn_atf_results, sn_atf_readiness, sn_atf
Flow Designer (read-only)sn_flow_view
Profilessn_profile
Natural languagesn_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_* and SN_PROFILE_NAME variables below build a profile only when ~/.servicenow-mcp/config.json does not exist. With a profile file present, put the rules on the profile with servicenow-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.


Tools Reference

Core CRUD

ToolDescription
sn_queryQuery 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_getGet a single record by sys_id from an approved table
sn_createCreate 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_updateUpdate 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_commentAppend one bounded customer-visible comment to an incident; repeated calls append again
sn_incident_add_work_noteAppend one bounded internal work note to an incident; repeated calls append again
sn_deleteDelete a record on an approved write table (requires confirm: true)
sn_batchBulk 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

ToolDescription
sn_aggregateCOUNT, AVG, MIN, MAX, SUM with grouping
sn_schemaTable field definitions, types, references
sn_healthInstance version, cluster nodes, stuck jobs, key stats

CMDB & Operations

ToolDescription
sn_relationshipsCMDB CI graph traversal — upstream/downstream/both, configurable depth
sn_attachList attachments, return downloads as inline base64, and upload inline base64 content; never touches a host filesystem path
sn_syslogQuery 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_codesearchSearch 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_discoverDiscover 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_on second, so the cursor holds the second and the row's sys_id, and a call returns the rows after that pair. It is an opaque token: pass it back as given.
  • has_more. If more than limit entries are waiting, the call returns limit of them with has_more: true and 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 no total and no next_offset, and offset cannot be combined with a tail.
  • Same filters on every call. The cursor is bound to the level, source and message it 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. since applies to the first call only, but a cursor older than the longest since (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_syslog read. A tail also reads sys_id and sys_created_on to 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

ToolDescription
sn_atf_authorCreate tests/suites, ordered memberships and validated typed steps
sn_atfLegacy test/suite listing and results; execution redirects to sn_atf_run
sn_atf_readinessCheck plugins, properties, Cloud Runner installation and permissions
sn_atf_runExecute a suite through Cloud Runner only, with bounded polling
sn_atf_resultsFetch results, cached history and comparisons
sn_nlCurrently 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

ToolDescription
sn_flow_viewShow 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

ToolDescription
sn_profileInspect 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!