snow-mcp

An MCP (Model Context Protocol) server for interacting with a ServiceNow instance via its Table API. Exposes tools to list/search, get, create, and update records in the incident, sc_request (Request), and sc_req_item (Requested Item) tables, plus generic tools that work against any ServiceNow table by name.

Setup

Requires Python >=3.14 and uv.

1. Create a .env file in the project root with your ServiceNow instance credentials:

   SERVICENOW_INSTANCE_URL="https://your-instance.service-now.com"
   SERVICENOW_USER="your-username"
   SERVICENOW_PASS="your-password"
   
   # Optional, only used when running over HTTP (see below):
   MCP_TRANSPORT="stdio"    # "stdio" (default) or "http"
   MCP_HOST="127.0.0.1"     # HTTP bind host, default 127.0.0.1
   MCP_PORT="8000"          # HTTP bind port, default 8000
   

2. Install dependencies:

   uv sync
   

Testing

uv run pytest

The suite mocks ServiceNow's HTTP API (via respx) and never talks to a real instance, so it runs without a .env file. It combines an in-process MCP client (mcp.shared.memory.create_connected_server_and_client_session, connected to the server over in-memory streams) with direct unit tests of ServiceNowClient. See tests/ and the Testing section of CLAUDE.md for details.

Running

Start the server over stdio (for use by an MCP client):

uv run main.py

To test interactively with the MCP Inspector:

uv run mcp dev main.py

Running over HTTP

Set MCP_TRANSPORT=http (in .env or the environment) and run the server the same way:

MCP_TRANSPORT=http uv run main.py

This serves both MCP HTTP transports from one process, bound to MCP_HOST/MCP_PORT (default 127.0.0.1:8000):

• Streamable HTTP (current spec): http://127.0.0.1:8000/mcp
• SSE (legacy transport): http://127.0.0.1:8000/sse

Stdio remains the default transport; the client-registration example below is unaffected by this.

Registering with an MCP client

{
  "mcpServers": {
    "snow-mcp": {
      "command": "uv",
      "args": ["run", "--directory", "C:\\Projects\\AI\\MCP\\snow-mcp", "main.py"]
    }
  }
}

Running in a container (Podman, Windows)

Requires Podman on Windows with a running machine (podman machine init once, then podman machine start). The image runs as a non-root user and serves the HTTP transport (MCP_TRANSPORT=http) so it's reachable from the host over the published port.

1. Make sure your .env file exists in the project root (see Setup above) — compose.yaml loads it via env_file.

2. Build and start:

   podman compose up -d --build
   

   (If podman compose isn't available, use podman-compose up -d --build instead — Podman shells out to whichever compose provider is installed.)

3. The server is now reachable at http://127.0.0.1:8000/mcp (streamable HTTP) — point an HTTP-based MCP client at it, same as the MCP_TRANSPORT=http case above.

4. Stop it:

   podman compose down
   

To build/run without compose:

podman build -f Containerfile -t snow-mcp .
podman run -d --name snow-mcp -p 8000:8000 --env-file .env -e MCP_TRANSPORT=http snow-mcp

Tools

Per-table tools (same shape for incident, sc_request → *_requests, sc_req_item → *_requested_items):

• list_incidents / list_requests / list_requested_items — search with an encoded query (query), sort (order_by, order_desc), pagination (limit, offset), field selection (fields), and display values (display_value)
• get_incident / get_request / get_requested_item — fetch a single record by sys_id
• create_incident / create_request / create_requested_item — create a record from a fields dict
• update_incident / update_request / update_requested_item — partially update a record by sys_id
• get_incident_work_notes / get_request_work_notes / get_requested_item_work_notes — read a record's work notes (journal entries) newest first, with limit/offset pagination and optional author filtering (created_by, exact username match)
• add_incident_work_note / add_request_work_note / add_requested_item_work_note — append a work note (note) to a record by sys_id

Generic tools, for any table by technical name:

• list_table_records, get_table_record, create_table_record, update_table_record

There is no delete tool.