Skip to main content
Glama
servicenow-mcp

servicenow-mcp

servicenow-mcp

An MCP server that connects Claude (or any MCP client) to your own ServiceNow instance through its standard REST API (Table API and Attachment API).

  • Works with any instance: a personal developer instance or a company one.

  • You sign in as yourself in the browser (OAuth with PKCE). No password is ever typed into or stored by this tool, and it can only see what your ServiceNow user can see.

  • Read-only unless you turn writes on.

  • Changes can go through a plan: you see the exact before and after of every field before anything is written, and you can undo it or check it for drift later.

  • One file, Node 18 or newer, no npm packages.

Quick start

There are three steps: register an OAuth client on your instance (once), sign in, and add the server to your MCP client.

1. Register an OAuth client on your instance

This needs the admin role. On a company instance, ask your ServiceNow admin to do it and send you the client id.

  1. In ServiceNow open System OAuth > Application Registry and choose New, then the option to create an OAuth API endpoint for external clients (on newer releases this is called a new inbound integration).

  2. Grant type: Authorization code.

  3. Client type: Public (no client secret, PKCE is used instead).

  4. Redirect URL: http://localhost:8787/callback

  5. Save it and copy the Client ID.

One client id can be shared by everyone on the same instance. Each person still signs in as themselves.

2. Sign in

npx -y github:MDK-s-Organisation/servicenow-mcp login

It asks for your instance and the client id, then opens the ServiceNow sign in page in your browser. When you approve, the tab says you can close it and the terminal prints who you are signed in as.

For the instance you can type the short name (dev12345), the host (acme.service-now.com) or the full URL (https://acme.service-now.com).

You can also pass everything up front:

npx -y github:MDK-s-Organisation/servicenow-mcp login --instance dev12345 --client-id <id>

Options: --instance <url or name>, --client-id <id>, --port <n> (default 8787, must match the redirect URL), --no-open (only print the link, do not open the browser).

3. Add it to your MCP client

login saves the instance, client id and port, so the server needs no extra settings.

Claude Code:

claude mcp add servicenow -- npx -y github:MDK-s-Organisation/servicenow-mcp

Claude Desktop, Cursor, VS Code and other clients that use a JSON config:

{
  "mcpServers": {
    "servicenow": {
      "command": "npx",
      "args": ["-y", "github:MDK-s-Organisation/servicenow-mcp"]
    }
  }
}

Then ask your assistant something like "show my instance info" to check the connection.

Related MCP server: ServiceNow MCP Server

Running from a clone

If you prefer not to use npx:

git clone https://github.com/MDK-s-Organisation/servicenow-mcp.git
cd servicenow-mcp
node server.mjs login

There is nothing to build and nothing to npm install. Register it with the absolute path to the file:

claude mcp add servicenow -- node /absolute/path/to/servicenow-mcp/server.mjs

Commands

node server.mjs            # run as an MCP server over stdio (what the MCP client starts)
node server.mjs login      # sign in
node server.mjs status     # instance, signed in or not, token expiry, write mode, plans folder
node server.mjs logout     # delete the saved tokens

With npx, put the command after the package name, for example npx -y github:MDK-s-Organisation/servicenow-mcp status.

Tools

Read tools, always available:

Tool

What it does

sn_instance_info

Instance URL, signed in user, build tag, whether writes are allowed

sn_table_query

Query a table (encoded query, fields, limit up to 200, offset, order, display values)

sn_table_get

Read one record by sys_id

sn_table_schema

Columns of a table, from sys_dictionary

sn_attachment_list

List attachments of a table or a record

sn_attachment_download

Save an attachment to a local file (never returns the contents)

Write tools, listed but refused unless writes are on:

Tool

What it does

sn_table_create

Create a record

sn_table_update

Change fields on a record

sn_table_delete

Delete a record

sn_attachment_upload

Attach a local file to a record

sn_attachment_delete

Delete an attachment

Reviewed changes, see Reviewed changes:

Tool

What it does

sn_plan_change

Save a plan with the before and after of every field, and check each value against the dictionary. Only reads ServiceNow, so it works with writes off

sn_apply_plan

Write a plan, after checking the record did not change since. Then read it back and report any difference

sn_undo_plan

Put the old values back (or delete the record the plan created), unless someone changed them since

sn_check_plan

Compare a plan with the record as it is now: can it still be applied, or has it drifted

Read-only by default

There are three settings for SN_ALLOW_WRITE:

Value

What can write

not set

Nothing. Plans can still be made and checked, but not applied

plan

Only sn_apply_plan and sn_undo_plan. The direct create, update, delete and upload tools refuse, so every change is a plan someone looked at first

1

Every write tool. Plans are there when you want them

Set it where the server is registered:

claude mcp add servicenow -e SN_ALLOW_WRITE=plan -- npx -y github:MDK-s-Organisation/servicenow-mcp

In a JSON config, add "env": { "SN_ALLOW_WRITE": "plan" } next to command and args.

A refused tool returns a clear message and sends nothing to ServiceNow. Even with writes on, the server can only do what your ServiceNow user is allowed to do.

Reviewed changes: plan, apply, undo, check

Say you ask: "put INC0010023 on hold and assign it to Bob".

  1. Plan. The assistant calls sn_plan_change. The server reads the record and saves a plan like this one. Nothing is written.

    plan 20261016-101500-1a2b3c4d   incident <sys_id>
      state        "2"                 ->  "3"
      assigned_to  "<sys_id>" (Ada)    ->  "<Bob's sys_id>"
      priority     already "2", left out

    The plan also keeps the record's sys_mod_count, the counter ServiceNow raises on every save.

  2. Review. The assistant shows you the plan and asks. If you say no, nothing ever reaches the instance.

  3. Apply. sn_apply_plan reads the record again. If the counter moved, someone changed the record after you reviewed it, so it stops and writes nothing. Otherwise it sends exactly the planned fields, reads the record back, and tells you about any field ServiceNow stored differently, for example because a business rule changed it.

  4. Undo. If the result is not what you wanted, sn_undo_plan puts the old values back. It refuses if someone changed those fields since, so it never overwrites later work. Fields outside the plan are left alone. For a plan that created a record, undo deletes that record.

  5. Check. sn_check_plan can run any time later. It lists each planned field that no longer holds what the plan left there, with the value now and who changed the record last.

Field checks while planning

Many failed first tries can be seen before anyone reviews the plan. While planning, sn_plan_change reads the dictionary of the table and of the tables it extends (incident extends task), including dictionary overrides, and checks every planned value:

Check

Example warning

Choice list

"4" is not a choice for incident.state. The choices are: 1 (New), 2 (In Progress), ...

Reference

"Bob Caller" is not a sys_id, or There is no sys_user record with sys_id ...

Type

"high" is not a whole number, but priority is an integer column, and the same for true or false and decimal columns

Length

The value is 200 characters long, but short_description holds at most 160

Read only

number is read only in the dictionary

Mandatory

a mandatory column the plan empties, or for a new record, one it leaves out and that has no default

Choices come from the nearest table that defines any, the same way ServiceNow picks them: incident has its own state choices, so the ones of task do not count for an incident. For a new record, a column that does not exist on the table or its parents stops the plan. Everything else is a warning saved with the plan, so the assistant can fix the plan before showing it to you, or show you the warnings next to the changes.

The checks only read. If the dictionary cannot be read, for example because your user may not read sys_dictionary, the plan is still made and carries one warning saying the checks were skipped.

When the first try does not work:

  • ServiceNow refuses the write (an ACL or a data policy). Nothing changed. The plan stays unapplied with the reason kept in it, and the assistant makes a new plan for you to review.

  • The write lands but is wrong. Undo it in one call, then plan again.

  • It takes several tries. Each try is a different change, so it needs a fresh look. To keep the rounds down, try things on a sub-production instance first and bring only the final plan to the instance that matters.

Give reference fields as sys_ids and choice fields as their stored values, the form sn_table_get returns by default, so the plan compares like with like.

Plans are JSON files in the plans folder next to the config file (~/.config/servicenow-mcp/plans by default). The folder is mode 0700 and each file 0600. A plan only works on the instance it was made for, and the server checks a plan file again before using it, in case it was edited by hand.

Limits:

  • The Table API has no "update only if unchanged" option. A change that lands in the moment between the final check and the write is not caught then, but the read back and sn_check_plan show it.

  • One record per plan, and only creates and updates. Deletes and attachments do not go through plans.

  • The field checks read the dictionary, not data policies, business rules or ACLs, so a write can still be refused or changed for those reasons. The read back after the write shows what was stored.

  • The approval is the assistant showing you the plan and your MCP client asking before it runs sn_apply_plan. The server has no approve button of its own.

Settings

Environment variables, all optional once you have signed in:

Variable

Default

SN_INSTANCE

none, login asks for it or takes --instance

SN_CLIENT_ID

none, login asks for it or takes --client-id

SN_CLIENT_SECRET

none, only for an OAuth client that was registered with a secret

SN_REDIRECT_PORT

8787

SN_TOKEN_FILE

~/.config/servicenow-mcp/tokens.json

SN_CONFIG_FILE

~/.config/servicenow-mcp/config.json

SN_ALLOW_WRITE

unset, writes are off unless this is exactly 1 (every write tool) or plan (only through plans)

SN_PLAN_DIR

plans in the folder of the config file

The config file may hold instance, clientId, redirectPort and allowWrite (true or "plan"). Environment variables win over the file.

If your admin registered a confidential client (one with a secret), set SN_CLIENT_SECRET both when you run login and where the server is registered. The secret is read from the environment only and is never written to disk by this tool.

To use two instances, give each its own files with SN_TOKEN_FILE and SN_CONFIG_FILE, and register the server twice under different names. Each one keeps its plans next to its own config file.

Where tokens are kept

Tokens are stored in ~/.config/servicenow-mcp/tokens.json. The folder is created with mode 0700 and the file with mode 0600, so only your user can read it. The access token is renewed automatically with the refresh token. Tokens are never printed, logged or returned by any tool. The instance must use https (plain http is accepted for localhost only), and a saved sign in is never sent to a different instance.

To sign out run the logout command. This deletes the token file. To also end the session on the ServiceNow side, revoke the token there under System OAuth > Manage Tokens.

Troubleshooting

  • "No ServiceNow instance is set": run login first, or set SN_INSTANCE.

  • The browser shows an invalid redirect error: the redirect URL on the OAuth client must be exactly http://localhost:8787/callback. If you use --port, change it on the instance too.

  • "ServiceNow answered with a redirect instead of data": a developer instance goes to sleep when unused. Wake it at developer.servicenow.com and try again.

  • A table returns nothing or a 403: your ServiceNow user lacks access to it. The server never goes around ServiceNow access controls.

Tests

node test/run-tests.mjs

The tests start a local mock of ServiceNow (test/mock-servicenow.mjs), run the whole sign in flow and every tool against it, and print PASS or FAIL lines. They never contact a real instance, never open a browser, and keep their token and config files in a temporary folder.

License

MIT, see LICENSE.

Available Tools

15 tools
sn_apply_planA
Destructive

Write a plan made by sn_plan_change, only after the user has agreed to its changes. For an existing record it first reads the record again and refuses if anything changed since the plan was made. It sends exactly the planned fields, then reads the record back and reports any field ServiceNow stored differently, for example because a business rule changed it. If ServiceNow refuses the write, nothing changes and the plan stays unapplied with the reason kept in it. This is a write tool. It refuses to run unless the server was started with SN_ALLOW_WRITE=1 or SN_ALLOW_WRITE=plan.

Inputs: plan_id (required).

sn_attachment_deleteA
Destructive

Delete one attachment from ServiceNow. This cannot be undone. This is a write tool. It refuses to run unless the server was started with SN_ALLOW_WRITE=1.

Inputs: sys_id (required).

sn_attachment_downloadA

Download one attachment from ServiceNow and save it to a local file. Returns the path and size only, never the file contents. Refuses to replace an existing file unless overwrite is true.

Inputs: sys_id (required), save_to (required), overwrite.

sn_attachment_listA
Read-only

List file attachments. Give table and sys_id to see the attachments of one record, or only table for every attachment on that table. Returns sys_id, file_name, content_type, size_bytes, table_name, table_sys_id and sys_created_on for each.

Inputs: limit, table, sys_id.

sn_attachment_uploadA

Upload a local file and attach it to a ServiceNow record. This is a write tool. It refuses to run unless the server was started with SN_ALLOW_WRITE=1.

Inputs: table (required), sys_id (required), file_path (required), file_name, +1 more.

sn_check_planA
Read-only

Compare a saved plan with the record as it is now. Before the plan is applied it says whether it can still be applied, or whether the record changed since the plan was made. After it is applied or undone it reports drift: each planned field that no longer holds the value sn_apply_plan or sn_undo_plan left there, and who changed the record last. Only reads.

Inputs: plan_id (required).

sn_instance_infoA
Read-only

Show which ServiceNow instance this server talks to, who is signed in, the instance build tag, and whether write tools are allowed. write_mode is off, plan (writes only through sn_apply_plan) or all. A good first call to check that the connection works.

Inputs: no named parameters.

sn_plan_changeA

Propose a change to one record without writing it. Give sys_id to change an existing record, or leave it out to plan a new one. The server reads the current values, saves a plan with the before and after value of every field, and returns it with a plan_id. Only reads reach ServiceNow. It also checks each value against the dictionary (choice lists, references, whole numbers, true or false, length, read only, and for a new record unknown and mandatory columns) and returns what it finds as warnings, so a plan can be fixed before anyone reviews it. Give reference fields as sys_ids and choice fields as stored values, the form sn_table_get returns, so the plan compares like with like. Show the changes to the user and call sn_apply_plan only after they agree.

Inputs: table (required), record (required), reason, sys_id.

sn_table_createA

Create a new record in a ServiceNow table. This is a write tool. It refuses to run unless the server was started with SN_ALLOW_WRITE=1.

Inputs: table (required), record (required).

sn_table_deleteA
Destructive

Delete one record from a ServiceNow table. This cannot be undone. This is a write tool. It refuses to run unless the server was started with SN_ALLOW_WRITE=1.

Inputs: table (required), sys_id (required).

sn_table_getB
Read-only

Read one record from a ServiceNow table by its sys_id.

Inputs: table (required), sys_id (required), fields, display_value.

sn_table_queryA
Read-only

Read records from a ServiceNow table with the Table API. Returns count (records in this reply), total (all matching records, when the instance reports it) and records. Use limit and offset to page through large results.

Inputs: table (required), limit, query, fields, +3 more.

sn_table_schemaA
Read-only

List the columns defined on a ServiceNow table, read from sys_dictionary: column name, label, type, max length, whether it is mandatory, and the table a reference points to. Columns inherited from a parent table (for example task for incident) are listed under the parent table name.

Inputs: table (required).

sn_table_updateA
DestructiveIdempotent

Change fields on one existing record. Only the fields you send are changed. This is a write tool. It refuses to run unless the server was started with SN_ALLOW_WRITE=1.

Inputs: table (required), record (required), sys_id (required).

sn_undo_planA
Destructive

Undo a plan that sn_apply_plan wrote. For a changed record it puts back the values the planned fields had before. For a new record it deletes that record. It refuses if someone changed those fields (or the new record) after the plan was applied, so it never overwrites later work. Fields the plan did not touch are left alone. This is a write tool. It refuses to run unless the server was started with SN_ALLOW_WRITE=1 or SN_ALLOW_WRITE=plan.

Inputs: plan_id (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 15 tools

    Disambiguation4/5

    Each tool targets a clear resource+action (table CRUD, attachments, planning), so most are easily distinguished. The one blurry area is two write paths for records: direct sn_table_create/sn_table_update/sn_table_delete versus the plan workflow (sn_plan_change + sn_apply_plan), and an agent must infer from write_mode and descriptions which to use.

    Naming Consistency4/5

    Strong sn_-prefixed resource_verb pattern for tables (sn_table_query/get/create/update/delete/schema) and attachments (sn_attachment_list/upload/download/delete). The plan group deviates slightly (sn_plan_change is noun_verb while sn_apply_plan/sn_undo_plan/sn_check_plan are verb_noun), a minor inconsistency but still readable and grouped.

    Tool Count5/5

    15 tools map cleanly onto three coherent capability groups (table operations, attachments, plan workflow), and each tool earns its place. The count sits at the top of the ideal range without redundancy.

    Completeness5/5

    Full record lifecycle is covered (query, get, schema, create, update, delete), attachments have complete list/download/upload/delete coverage, and the plan workflow adds safe create/change/undo/verify. No obvious dead ends for the stated ServiceNow table-and-attachment purpose.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      D
      maintenance
      Enables Claude to interact with ServiceNow instances through comprehensive API integration. Supports incident management, service catalog operations, change requests, knowledge base management, user administration, and agile project management with multiple authentication methods.
      82
      MIT
    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables Claude to interact with ServiceNow instances for incident management, service catalog operations, change requests, knowledge base management, user administration, and agile project workflows through various authentication methods.
      MIT