servicenow-mcp-server

A complete Model Context Protocol (MCP) server for ServiceNow. Connect Claude (or any MCP client) to your ServiceNow instance and interact with incidents, changes, CMDB, service catalog, users, groups, and the knowledge base using natural language.

---

Authentication

Three auth methods are supported. Set the env vars for exactly one — the server detects which to use automatically.

Method	Env vars required	Best for
OAuth 2.0 PKCE	SERVICENOW_CLIENT_ID + SERVICENOW_CLIENT_SECRET	SSO / per-user permissions
Basic auth	SERVICENOW_USERNAME + SERVICENOW_PASSWORD	Dev / service accounts
Static token	SERVICENOW_ACCESS_TOKEN	Quick testing

Priority (if multiple are set): static token → basic → OAuth PKCE

---

Option A — OAuth 2.0 PKCE (recommended)

The PKCE flow authenticates as the real user. Each person who runs the server logs in via your SSO identity provider and gets access only to what their ServiceNow roles permit — admins can do admin things, itil users are limited to itil operations, and so on.

1. Create an OAuth application in ServiceNow

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

• Set Redirect URL to http://localhost:54321/callback
• Copy the Client ID and Client Secret

If you need a different callback port, set SERVICENOW_OAUTH_CALLBACK_PORT (default: 54321) and update the redirect URL in ServiceNow to match.

2. Configure your env vars

SERVICENOW_INSTANCE_URL=https://yourcompany.service-now.com
SERVICENOW_CLIENT_ID=your_client_id
SERVICENOW_CLIENT_SECRET=your_client_secret

# Optional — only needed if port 54321 is taken
# SERVICENOW_OAUTH_CALLBACK_PORT=54321

3. First-time login

Before adding to Claude Desktop, run the server once in a terminal to complete the browser login:

npx @autopilot715/servicenow-mcp-server

Your browser will open to your ServiceNow login (which will trigger SSO if configured). After authenticating, tokens are cached at ~/.config/servicenow-mcp-server/tokens.json. The server starts and you can Ctrl+C once you see it's running.

Subsequent starts (including from Claude Desktop) are silent — the cached token is used and refreshed automatically. A full re-login only happens if the refresh token expires or is revoked.

4. Add to Claude Desktop config

Mac: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "servicenow": {
      "command": "npx",
      "args": ["@autopilot715/servicenow-mcp-server"],
      "env": {
        "SERVICENOW_INSTANCE_URL": "https://yourcompany.service-now.com",
        "SERVICENOW_CLIENT_ID": "your_client_id",
        "SERVICENOW_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

Restart Claude Desktop after editing the config.

---

Option B — Basic auth

Simplest to set up. Use a dedicated service account in production rather than a personal login.

{
  "mcpServers": {
    "servicenow": {
      "command": "npx",
      "args": ["@autopilot715/servicenow-mcp-server"],
      "env": {
        "SERVICENOW_INSTANCE_URL": "https://yourcompany.service-now.com",
        "SERVICENOW_USERNAME": "your_username",
        "SERVICENOW_PASSWORD": "your_password"
      }
    }
  }
}

---

Option C — Static bearer token

Use an existing OAuth token. Tokens expire and require manual renewal.

{
  "mcpServers": {
    "servicenow": {
      "command": "npx",
      "args": ["@autopilot715/servicenow-mcp-server"],
      "env": {
        "SERVICENOW_INSTANCE_URL": "https://yourcompany.service-now.com",
        "SERVICENOW_ACCESS_TOKEN": "your_oauth_token"
      }
    }
  }
}

Tokens can be found or generated at System OAuth → Manage Tokens in ServiceNow.

---

Running Locally (from source)

git clone https://github.com/kylburns89/servicenow-mcp-server.git
cd servicenow-mcp-server
npm install
npm run build

Copy .env.example to .env and fill in your credentials:

cp .env.example .env

Then start with:

# Node 20+ (recommended)
node --env-file=.env dist/index.js

# Node 18
export $(grep -v '^#' .env | xargs) && node dist/index.js

For active development, run the TypeScript compiler in watch mode in one terminal and restart the server after each save:

npm run dev   # tsc --watch

---

Example Prompts

Once connected, you can use natural language:

• "Show me all P1 and P2 incidents assigned to the Network Operations group"
• "Create an incident for a login issue reported by jdoe@company.com, category software, high priority"
• "List all emergency change requests scheduled this week"
• "Find all servers in the Data Center that are in maintenance status"
• "Search the knowledge base for articles about VPN setup"
• "Get the full details for change request CHG0012345"
• "Add a work note to INC0001234 saying the server has been rebooted and is under monitoring"
• "Who are the members of the Service Desk group?"

---

Tools (41 total)

Generic Table API

Tool	Description
servicenow_query_records	Query any table with encoded filters and pagination
servicenow_get_record	Get a single record by sys_id
servicenow_create_record	Create a record in any table
servicenow_update_record	Update a record by sys_id (PATCH)
servicenow_delete_record	Delete a record by sys_id ⚠️

Incidents

Tool	Description
servicenow_list_incidents	List/search incidents with filters
servicenow_get_incident	Get incident by number (INC...) or sys_id
servicenow_create_incident	Create a new incident
servicenow_update_incident	Update state, assignment, priority, etc.
servicenow_add_work_note	Add a work note or comment to any record

Change Management

Tool	Description
servicenow_list_changes	List/search change requests
servicenow_get_change	Get change by number (CHG...) or sys_id
servicenow_create_change	Create a change request
servicenow_update_change	Update state, plans, assignment

Users & Groups

Tool	Description
servicenow_list_users	Search users
servicenow_get_user	Get user by username, email, or sys_id
servicenow_list_groups	List user groups
servicenow_get_group_members	Get all members of a group

CMDB

Tool	Description
servicenow_search_ci	Search CIs by name, class, or location
servicenow_get_ci	Get full CI details
servicenow_get_ci_relationships	Traverse upstream/downstream CI relationships (configurable depth)

Service Catalog

Tool	Description
servicenow_list_catalog_items	Browse catalog items
servicenow_get_catalog_item	Get item details and required variables
servicenow_submit_catalog_request	Submit a catalog request
servicenow_list_sc_requests	List catalog requests (REQ...)

Knowledge Base

Tool	Description
servicenow_search_knowledge	Search KB articles
servicenow_get_kb_article	Get full article content

Bulk Operations

Tool	Description
servicenow_bulk_update	Update multiple records matching a query (dry-run by default) ⚠️
servicenow_bulk_delete	Delete multiple records matching a query (dry-run by default) ⚠️

Attachments

Tool	Description
servicenow_list_attachments	List file attachments for a record
servicenow_get_attachment_content	Download attachment content (text inline, binary via URL)
servicenow_upload_attachment	Upload a file attachment to any record

Developer & Admin

Tool	Description
servicenow_aggregate	COUNT/SUM/AVG/MIN/MAX on any table, with optional grouping
servicenow_get_table_schema	Introspect field definitions from sys_dictionary
servicenow_get_instance_info	Instance version, cluster nodes, and upgrade history
servicenow_query_logs	Query syslog for errors, warnings, and debug messages
servicenow_search_artifacts	Search code across business rules, script includes, client scripts, UI actions, and scripted REST ops
servicenow_list_applications	List installed scoped applications
servicenow_discover_tables	Search and browse the table catalog (sys_db_object)
servicenow_list_atf_tests	List ATF tests and test suites
servicenow_run_atf_test	Execute an ATF test or suite via the ATF REST API

---

Query Syntax Reference

ServiceNow encoded query syntax for the query parameters:

Operator	Example	Meaning
=	state=1	Equals
!=	state!=7	Not equals
>=	priority>=2	Greater than or equal
LIKE	nameLIKEjohn	Contains
^	state=1^priority=1	AND
^OR	state=1^ORstate=2	OR
javascript:	assigned_to=javascript:gs.getUserID()	Script expression
STARTSWITH	numberSTARTSWITHINC	Starts with

---

Project Structure

src/
├── index.ts                       # Entry point, server init, transport selection
├── types.ts                       # TypeScript interfaces and field resolvers
├── constants.ts                   # Table names, state labels, limits
├── schemas/common.ts              # Shared Zod schemas
├── services/
│   ├── auth.ts                    # Auth mode detection, OAuth PKCE flow, token cache
│   └── servicenow-client.ts       # Axios client, Table API helpers
└── tools/
    ├── table.ts       # Generic CRUD tools
    ├── incidents.ts   # Incident tools
    ├── changes.ts     # Change management tools
    ├── users.ts       # User & group tools
    ├── cmdb.ts        # CMDB + CI relationship traversal tools
    ├── catalog.ts     # Service catalog tools
    ├── knowledge.ts   # Knowledge base tools
    ├── bulk.ts        # Bulk update/delete with dry-run
    ├── attachments.ts # Attachment list/upload/download
    └── developer.ts   # Aggregations, schema, logs, artifact search, ATF, app/table discovery

---

Contributing

Issues and PRs welcome on GitHub.

License

MIT