servicenow-mcp

An MCP server for managing ServiceNow incidents via the Table API. Exposes tools to create, read, update, search, comment on, and resolve incidents.

Setup

1. Install dependencies:

   uv sync
   

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

   cp .env.example .env
   

   • SERVICENOW_INSTANCE: the instance name only (e.g. dev12345 for dev12345.service-now.com)
   • SERVICENOW_USERNAME / SERVICENOW_PASSWORD: basic auth credentials for a user with access to the incident table (read/write via the Table API)

3. Run the server directly to sanity-check it starts:

   uv run servicenow-mcp
   

Using with Claude Desktop / Claude Code

There are two ways to connect, depending on whether you want everyone using the server to share one ServiceNow service account, or each person to authenticate as themselves. See Authentication below for the full picture.

Option A — stdio, shared service account

The client launches the server itself as a subprocess; every tool call uses the SERVICENOW_USERNAME / SERVICENOW_PASSWORD passed in via env.

{
  "mcpServers": {
    "servicenow": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/servicenow-mcp", "run", "servicenow-mcp"],
      "env": {
        "SERVICENOW_INSTANCE": "your-instance",
        "SERVICENOW_USERNAME": "your-username",
        "SERVICENOW_PASSWORD": "your-password"
      }
    }
  }
}

Option B — HTTP, per-client credentials

Start the server once as a long-running HTTP process (it only needs SERVICENOW_INSTANCE, plus SERVICENOW_USERNAME/PASSWORD as a fallback for requests with no auth header):

uv run servicenow-mcp --transport streamable-http --host 127.0.0.1 --port 8003

Then point .mcp.json at it and send your own ServiceNow login as an HTTP Basic Auth header — this is what makes the connection "client level": the credentials live in your client config, not the server's:

{
  "mcpServers": {
    "servicenow": {
      "type": "http",
      "url": "http://127.0.0.1:8003/mcp",
      "headers": {
        "Authorization": "Basic <base64 of your-username:your-password>"
      }
    }
  }
}

Generate the base64 value from a terminal (note the leading space, which -n on echo avoids):

echo -n "your-username:your-password" | base64

.mcp.json isn't covered by .gitignore the way .env is — don't commit real credentials into it if this directory ever becomes a shared/git repo.

Tools

• create_incident — create a new incident
• get_incident — fetch by number (e.g. INC0010023) or sys_id
• update_incident — update arbitrary fields
• search_incidents — search with a ServiceNow encoded query (sysparm_query)
• add_comment — add a customer-visible comment or internal work note
• resolve_incident — set state to Resolved with close notes/code

Authentication

Auth is basic auth (username/password). Where those credentials come from depends on transport:

• stdio: always uses the shared SERVICENOW_USERNAME / SERVICENOW_PASSWORD from .env.

• HTTP (sse / streamable-http): each request can authenticate as its own ServiceNow user by sending a standard HTTP Basic Auth header:

  Authorization: Basic base64(username:password)
  

  SERVICENOW_INSTANCE stays server-side (it's one instance for all clients), but the username/password are per-client — so search_incidents results, caller_id resolution, etc. reflect that individual user's ServiceNow permissions instead of one shared service account. If a request has no Authorization header, it falls back to the shared SERVICENOW_USERNAME / SERVICENOW_PASSWORD from .env.

If you need OAuth 2.0 later, swap the requests.Session.auth setup in src/servicenow_mcp/client.py for a token-based flow — the rest of the client is auth-agnostic.

Notes

• The incident table's state field is numeric (e.g. 6 = Resolved, 7 = Closed); values can differ if your instance customizes incident states.