ServiceNow Change Request and Incident MCP Server
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
ServiceNow Change Request and Incident MCP Server
An MCP (Model Context Protocol) server that lets
AI assistants query ServiceNow incidents and query, summarize, create, and update
change_request records, plus query and create Method of Procedure (u_mop)
records, using natural language.
It works both as a local single-user server (stdio / CLI) and as a remote multi-user server (HTTP) where each user's CI credentials are passed through per request.
Current version:
0.1.0— see the Changelog for the full release history.
Usage
Prerequisite: get your CI client id & client secret
This server authenticates to ServiceNow on your behalf using a CI
Account (client_id + client_secret). Request your own pair from your
identity team first — never reuse someone else's.
Keep the client_secret private: put it in your local .env (gitignored) or in
your MCP client headers — never commit it or paste it into shared configs.
A. Local (single user) — stdio / CLI / debugging
Set up the environment and credentials:
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e .
cp .env.example .env # then edit .envPut your own credentials in .env:
Variable | Description |
| ServiceNow instance URL (required) |
| CI identity service base URL (default |
| Scripted REST path that exchanges a CI token for a SNOW token (default |
| Your CI client id |
| Your CI client secret |
Other local auth options:
Method | Variables |
Manual token |
|
Basic Auth |
|
FedRAMP | add |
Run it:
# MCP server (stdio, for Cursor/VS Code to spawn)
MCP_TRANSPORT=stdio python -m mcp_servicenow_chg
# MCP server (HTTP transport, default)
python -m mcp_servicenow_chg
# CLI queries
python -m mcp_servicenow_chg get CHG0768536 [--verbose]
python -m mcp_servicenow_chg list "Frank Rang" --from-date 2026-03-01 --orGenerate a token by itself (optional). generate-snow-token is a console
script installed by this project, so it only exists on PATH once this repo's
own virtualenv is active — activating an unrelated venv gives
command not found. The python -m form is equivalent:
generate-snow-token --snow # SNOW token (for SERVICENOW_TOKEN)
generate-snow-token # CI token only
python -m mcp_servicenow_chg.token_cli --snow # same, via the moduleCursor / VS Code config (stdio)
The repo ships a .cursor/mcp.json so Cursor spawns the server automatically.
Do not put URLs or credentials in the env block — keep them in .env
(gitignored), which is loaded automatically at startup.
{
"mcpServers": {
"servicenow-chg": {
"command": ".venv/bin/python",
"args": ["-m", "mcp_servicenow_chg"],
"cwd": "${workspaceFolder}",
"env": { "MCP_TRANSPORT": "stdio" }
}
}
}After the first setup, fully restart Cursor once so the config takes effect.
B. Remote (multi-user) — via the MCP Market
When deployed, the server is published in the internal MCP Market. Users install it from the market and connect over HTTP(S). Each user supplies their own CI credentials (see Prerequisite above) via request headers; the server passes them through to ServiceNow per request and stores nothing.
Three accepted ways to send credentials (use whichever your client supports):
Option | Header(s) |
Single header (recommended) |
|
Two headers |
|
HTTP Basic |
|
If multiple are present, the two discrete headers take priority, then
X-CI-CLIENT-AUTH, then Authorization: Basic.
Client config example (VS Code settings.json / Cursor mcp.json):
{
"servers": {
"servicenow-chg": {
"url": "https://mcp.example.com/mcp/",
"headers": {
"X-CI-CLIENT-AUTH": "<client_id>:<client_secret>"
}
}
}
}Two-header equivalent:
{
"servers": {
"servicenow-chg": {
"url": "https://mcp.example.com/mcp/",
"headers": {
"X-CI-CLIENT-ID": "<your client id>",
"X-CI-CLIENT-SECRET": "<your client secret>"
}
}
}
}Requires network access to the deployed server. Auth priority on the server is: request-header credentials >
SERVICENOW_TOKEN> env CI credentials > Basic Auth.
Related MCP server: servicenow-mcp-server
Project Structure
mcp-servicenow-chg/
├── src/mcp_servicenow_chg/
│ ├── __init__.py
│ ├── __main__.py # Entry point: python -m mcp_servicenow_chg
│ ├── server.py # MCP server + tools + auth resolution
│ ├── incidents.py # Incident query validation and construction
│ ├── token.py # CI -> SNOW token exchange & auto-renew (TokenHolder)
│ ├── token_cli.py # CLI: generate-snow-token
│ ├── resources.py # MCP resources (schema, query syntax, states)
│ └── prompts.py # MCP prompts
├── Dockerfile # Container image (plain HTTP; TLS terminated upstream)
├── pyproject.toml
├── .env # Local config (gitignored — never commit)
├── .env.example
└── README.mdWhat an MCP server exposes: Tools, Resources, Prompts
MCP servers offer three kinds of capabilities to an AI client. This server uses all three:
1. Tools — actions the model can execute
Tools are callable functions. The model decides when to call them and with what arguments; each call performs a real operation (here, a ServiceNow Table API request) and returns structured data.
Tool | Description |
| Fetch a single change by number (e.g. |
| Query multiple changes with a ServiceNow encoded query |
| List changes by assignee with filters ( |
| Convert a change record into a concise text summary |
| Fetch and summarize in one call |
| PATCH a change by number ( |
| Fetch a single incident by number (e.g. |
| Query incidents by priority, data center, impacted business service, liable service, and UTC time range |
| Search MOP records by keyword (u_name / u_title) |
| Fetch a single MOP by number (e.g. MOP0001234.1) |
| Create a MOP record after validating required planning fields and resolving group/creator/reviewer references |
| Resolve and validate all required fields before create |
| Create a new change — |
create_changetypes & required fields: Settypetostandard(default),normal, oremergency. Common required fields for all types:short_description,cmdb_ci,business_service,u_data_center,assignment_group,assigned_to,start_date(UTC),end_date(UTC). Per type, additionally:standard/normalrequireu_mop;emergencyrequiresu_emergency_justification.Verify-first workflow: Call
verify_create_fieldsbefore create. It resolves reference fields against ServiceNow; ambiguous matches (e.g. duplicate CI or assignee names) return candidates for user confirmation.create_changeruns verify by default (skip_verify=trueto bypass).Schedule (no default timezone): Pass
schedule_timezone(IANA or UTC offset) withschedule_start_local/schedule_end_local, or pass UTCstart_date/end_datedirectly. The server never assumes a default timezone.Profile (explicit opt-in): Pass
profile(e.g.example_change) only when the user requests a named preset; profiles are never auto-selected.Auto-handled (pass a value to override):
requested_byis omitted when absent (ServiceNow fills it with the submitting user);descriptionis generated fromshort_descriptionwhen absent (standard/normal also reference the MOP);statedefaults to Scheduled (-2) forstandardand New (-5) fornormal/emergency. The standard default state is overridable viaSNOW_CHG_SCHEDULED_STATE.
list_incidents combines all supplied filters with AND. Priority accepts values
1-5, P1-P5, or labels such as Critical and High. Date-only time
bounds are accepted; an end date includes the full UTC day. The default time
field is opened_at, and callers can select resolved_at, closed_at,
sys_created_on, or sys_updated_on.
Impacted Business Service and Liable service use fuzzy LIKE matching by
default (fuzzy_services=false requests exact names). Their reference query
paths, and the data-center query path, can be overridden with the
SNOW_INCIDENT_*_QUERY_FIELD environment variables documented below.
2. Resources — read-only reference context
Resources are read-only documents the client can load into the model's context to ground its answers (schemas, references, lookup tables). They are not actions; they are data.
URI | Description |
| Common |
| Common incident fields and supported filters |
| MOP table fields (search_mops / get_mop / create_mop) |
| ServiceNow encoded query syntax reference |
| State value reference (configurable via env) |
3. Prompts — reusable, parameterized templates
Prompts are pre-written instruction templates the user can pick from the client UI. They expand into a ready-to-run message that typically tells the model which tools to use.
Prompt | Parameters | Description |
|
| Look up one change and summarize it |
|
| List changes by assignee |
|
| Bulk-check the status of several changes |
|
| Verify fields, confirm with user, then create a change |
|
| Turn an incident-search request into a structured |
Deployment (Container / Kubernetes)
The repo provides a Dockerfile: non-root, minimal image, streamable-http,
listening on 0.0.0.0:8000 at path /mcp.
The container serves plain HTTP only. TLS is terminated in front of it by a reverse proxy (nginx/Caddy/Envoy) or a platform ingress (e.g. Kubernetes) — the standard pattern for remote MCP servers. The app stays simple; cert rotation, HTTP/2, and security hardening live in the proxy.
docker build -t mcp-servicenow-chg .
docker run -p 8000:8000 -e SERVICENOW_INSTANCE=https://your-instance.service-now.com mcp-servicenow-chgConfiguration notes:
SERVICENOW_INSTANCEis required. SetCI_BASE_URLandSNOW_CI_EXCHANGE_PATHto match your identity service and the scripted REST API on your instance (and optionallyCI_ENV).State codes default to
3(Closed) /4(Canceled); override withSNOW_CHG_CLOSED_STATE/SNOW_CHG_CANCELED_STATEif your instance differs.Incident query paths default to
u_data_center.name,u_impacted_service.name, andbusiness_service.name. Override them withSNOW_INCIDENT_DATA_CENTER_QUERY_FIELD,SNOW_INCIDENT_IMPACTED_SERVICE_QUERY_FIELD, andSNOW_INCIDENT_LIABLE_SERVICE_QUERY_FIELDif your incident dictionary differs.Never bake any user credentials into the image or environment. Per-user credentials always arrive as request headers.
Typical topology:
MCP client --HTTPS--> reverse proxy / Kubernetes ingress --HTTP--> container :8000 /mcpAuthentication & Token Call Flow
This server never stores user secrets. For each request it resolves credentials, exchanges them for a ServiceNow token, and reuses that token until it nears expiry.
Per-request resolution
Read credentials from the request headers —
X-CI-CLIENT-ID/X-CI-CLIENT-SECRET, or a singleX-CI-CLIENT-AUTH: client_id:client_secret, orAuthorization: Basic base64(client_id:client_secret)(deployed / multi-user mode) — or fall back to local env auth (SERVICENOW_TOKEN, then env CI credentials, then Basic Auth).Look up (or create) a
TokenHolderfor those credentials in a bounded, in-memory LRU cache keyed bysha256(client_id:client_secret)— the raw secret is never used as a key and never logged. The cache is capped (LRU eviction) so memory cannot grow unbounded under many users.
Token exchange (two steps)
TokenHolder obtains a ServiceNow Bearer token via CI:
client_id + client_secret
│ (1) POST <CI_BASE_URL>/idb/oauth2/v1/access_token (Basic auth, client_credentials)
▼
CI access_token
│ (2) POST <snow_instance><SNOW_CI_EXCHANGE_PATH>
▼
ServiceNow access_token -> "Bearer <token>" (with expires_in)(For FedRAMP, CI_ENV=fedramp uses CI_FEDRAMP_BASE_URL.)
Refresh & expiry strategy
The SNOW token lifetime is ~1 hour (
expires_infrom the exchange).The token is refreshed proactively
REFRESH_BUFFER_SECONDS = 300(5 min) before its real expiry, so a token is never used right as it expires mid-request.On a
401from ServiceNow, the holder invalidates its token and retries the request once with a freshly fetched token.A manually supplied
SERVICENOW_TOKENis treated as static (never refreshed).
Development & Debugging
Install dev extras (adds debugpy):
pip install -e ".[dev]"HTTP + breakpoint debugging:
Set breakpoints in
src/mcp_servicenow_chg/server.py.Start the server (
python -m mcp_servicenow_chg) so it listens onhttp://127.0.0.1:8000/mcp.In Cursor: Settings → Tools & MCP → Add new MCP server → Streamable HTTP, URL
http://127.0.0.1:8000/mcp.Invoke a tool from chat; the breakpoint hits when the request arrives.
Verify the connection by asking, e.g.: "Use get_change_summary to look up CHG0001234." You can also use the MCP Inspector against the stdio or HTTP endpoint.
Example: list_changes_by_assignee
# Frank Rang, March onward OR not closed
list_changes_by_assignee(
assigned_to="Frank Rang",
from_date="2026-03-01",
from_date_or_not_closed=True,
limit=50,
)Example: list_incidents
list_incidents(
priority="P1",
data_center="DC01",
impacted_business_service="Calling",
liable_service="Media",
start_time="2026-09-01",
end_time="2026-09-02",
)Troubleshooting
Symptom | Fix |
Cursor doesn't detect the MCP | Fully quit and restart Cursor |
Tools not found | Check the python path / URL in |
401 / 403 errors | Tokens auto-renew; if it still fails, check your credentials / headers |
Breakpoints not hit | Ensure the HTTP server is running and Cursor is connected to that endpoint |
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Remote MCP server exposing your Node Command fleet (files, shell, processes, browser) to AI hosts.
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
Marketo MCP server for AI. 130 tools to operate Marketo from Claude, Cursor, or ChatGPT.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that enables AI assistants and development tools to interact with ServiceNow instances, providing comprehensive API coverage for incident management, change management, CMDB, and other ServiceNow modules.3MIT
- AlicenseAqualityDmaintenanceEnables natural language interaction with ServiceNow instances for managing incidents, changes, CMDB, service catalog, users, groups, and knowledge base via MCP.4131 npm1MIT
- AlicenseBqualityBmaintenanceEnables natural language control of ServiceNow from AI clients like Claude and Cursor. Provides 400+ tools for incidents, changes, CMDB, and scripts via MCP protocol.500183 npm2MIT
- FlicenseNot gradedqualityDmaintenanceA local gateway that exposes ServiceNow REST APIs as MCP tools, enabling natural language interaction with ServiceNow incidents, changes, CMDB, and scripts via Claude and other MCP clients.-