servicenow-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@servicenow-mcp Find all open incidents with high urgency"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
servicenow-mcp
A small MCP server that lets AI agents create, search and
update ServiceNow incidents through the Table API. Built with the official Python
mcp package (FastMCP-style decorators), httpx and python-dotenv. Runs over stdio.
Everything lives in a single file: server.py.
Setup
Requires Python 3.12+ and uv.
uv syncCreate a .env next to server.py (it is git-ignored) with basic-auth credentials for
your instance — a Personal Developer Instance works fine:
SNOW_INSTANCE_URL=https://devXXXXXX.service-now.com
SNOW_USERNAME=admin
SNOW_PASSWORD=your-password
# optional, default 15
SNOW_TIMEOUT_SECONDS=15Run the server (it speaks MCP over stdin/stdout, so there is nothing to see — an MCP client must launch it):
uv run server.pyRegistering with an MCP client
Point the client at uv with the project directory so the .venv and .env are picked up:
{
"mcpServers": {
"servicenow": {
"command": "uv",
"args": ["--directory", "/absolute/path/to/servicenow-mcp", "run", "server.py"]
}
}
}For Claude Code: claude mcp add servicenow -- uv --directory /absolute/path/to/servicenow-mcp run server.py.
Environment variables already set in the client's environment take precedence over .env.
Related MCP server: sn-mcp-bridge
Tools
Tool | Parameters | What it does | Returns |
|
| Creates a new incident. |
|
|
| Lists incidents newest first. |
|
|
| Looks the incident up by number, appends a work note and/or sets the state. At least one of |
|
All tools raise a readable tool error (surfaced to the agent as isError) instead of a
stack trace, e.g.:
Authentication failed (401): check SNOW_USERNAME and SNOW_PASSWORD. ServiceNow said: User is not authenticated …Could not connect to https://…: [Errno 8] nodename nor servname provided … Check SNOW_INSTANCE_URL and your network connection.Timed out after 15s talking to https://… The instance may be hibernating (PDI) or unreachable.Incident 'INC9999999' was not found on https://….Forbidden (403): the user lacks permission … or the update was rejected by a business rule. ServiceNow said: …(e.g. resolving an incident without resolution fields).
Design notes
ServiceNowClientwraps a singlehttpx.AsyncClient(basic auth, JSON headers, timeout) and exposescreate_record / query_records / get_record_by_number / update_record. All errors are translated toServiceNowErrorwith a human-readable message.The tools get the client through
get_client(); callset_client(fake)in tests to swap in a mock without touching the network.Records are fetched with
sysparm_display_value=all, so state/urgency labels come from the instance itself rather than a hard-coded map (the friendly-name aliases are input-only).mcp2.x renamedFastMCPtoMCPServer;server.pyimports whichever exists so it runs on both 1.x and 2.x.
Smoke test
Run against the live instance (writes one incident):
uv run python -c "
import asyncio, server
async def main():
c = await server.create_incident('MCP server smoke test', 'created by smoke test')
print(c)
print(await server.query_incidents(query_text='MCP server smoke test'))
print(await server.update_incident(c['number'], work_notes='hello from MCP'))
asyncio.run(main())
"Available Tools
3 toolscreate_incidentA
Create a new ServiceNow incident and return its number and sys_id.
Use this when a user reports a problem that should be tracked as a ticket.
Args:
short_description: One-line summary of the issue (required, shown in lists).
description: Longer free-text details, steps to reproduce, impact, etc.
urgency: "1" (High), "2" (Medium) or "3" (Low). Defaults to "3".
Returns:
{"number": "INC0010001", "sys_id": "...", "short_description": ..., "state": ..., "urgency": ...}
The `number` is what humans reference; `sys_id` is the stable record id.
Inputs: short_description (required), urgency, description. Returns: object
query_incidentsA
List ServiceNow incidents, newest first, optionally filtered by text and/or state.
Use this to find existing tickets before creating a new one, to check on a
ticket by number, or to answer "what incidents are open about X?".
Args:
query_text: What to search for. An incident number ("INC0010001") matches
exactly; anything else runs ServiceNow's keyword search over the
incident's text fields, falling back to a substring match on
short_description/description. Leave empty to list the most recent incidents.
state: Filter by state. Accepts a numeric code ("1".."8") or a name such as
"New", "In Progress", "On Hold", "Resolved", "Closed", "Canceled".
Leave empty for any state.
limit: Maximum number of incidents to return (1-100). Defaults to 5.
Returns:
A list of {"number", "sys_id", "short_description", "state", "state_code",
"urgency", "created_on"}; an empty list means nothing matched.
Inputs: limit, state, query_text. Returns: result
update_incidentA
Update an existing incident by number: append a work note and/or change its state.
Use this to record progress on a ticket or move it through its lifecycle.
At least one of `work_notes` or `state` must be provided.
Args:
number: The incident number, e.g. "INC0010001".
work_notes: Text to append to the (internal) work notes journal.
state: New state as a numeric code ("1".."8") or a name such as "In Progress",
"On Hold", "Resolved", "Closed". Note: resolving/closing on most instances
also requires resolution fields and will be rejected by ServiceNow if missing.
Returns:
{"number", "sys_id", "changed": {field: new value, ...}, "state": <current state>}
describing exactly what was applied.
Inputs: number (required), state, work_notes. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Each tool targets a distinct operation: create, query (list/search), and update. There is no overlap in purpose; an agent can clearly differentiate when to use each.
All tools follow a consistent verb_noun pattern using snake_case (create_incident, query_incidents, update_incident), with plural nouns for collection queries and singular for single-item operations, which is predictable.
With 3 tools, the set is minimal but covers the core incident lifecycle (create, read/search, update). It is slightly thin—missing a dedicated get_incident or delete_incident—but still well-scoped for a focused incident-only server.
The tools cover create, list/search, and update, but lack an explicit 'get by ID' tool (though query_incidents can filter by number) and a delete/close operation. The update tool warns about missing resolution fields for closing, indicating gaps in full lifecycle support.
Related MCP Connectors
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP server for OpenAI API (chat completions, image generation, embeddings) via AceDataCloud
MCP server for AI dialogue using various LLM models via AceDataCloud
MCP server that lets AI assistants use all OneSchema features exposed via the public API.
Related MCP Servers
- AlicenseAqualityDmaintenanceA production-ready MCP server that turns any MCP-compatible AI assistant into an AI-powered ServiceNow Incident Management Assistant, exposing incidents, users, CMDB records, and knowledge articles through validated tools.12MIT
- AlicenseNot gradedqualityCmaintenanceA lightweight MCP server that gives AI coding assistants full development capability on ServiceNow through the Table API, enabling CRUD and script execution without local installation.23 npmMIT
- FlicenseNot gradedqualityDmaintenanceMCP server that enables LLMs to interact with ServiceNow instances for managing incidents, users, stories, workflows, knowledge base articles, and script includes via the FastMCP framework.-
- AlicenseAqualityDmaintenanceAn MCP server for interacting with a ServiceNow instance via its Table API, enabling CRUD operations on incident, request, and requested item tables, as well as generic operations on any table by name.22MIT