ServiceNow Incident MCP Server

A production-ready Model Context Protocol (MCP) server that turns any MCP-compatible AI assistant (Claude, Cursor, etc.) into an AI-powered ServiceNow Incident Management Assistant. It exposes ServiceNow incidents, users, CMDB records, and knowledge articles through clean, validated MCP tools.

AI Assistant  ──►  MCP Server (Node.js + TypeScript)  ──►  ServiceNow REST API  ──►  ServiceNow Instance

Features

• 12 MCP tools across three phases (read, actions, AI-powered helpers).

• Reusable ServiceNow REST client (Axios) with Basic auth, request timeout, and exponential-backoff retry on transient failures.

• Zod-validated inputs for every tool.

• Structured logging to stderr with automatic secret redaction — passwords and auth headers are never logged.

• Self-contained, deterministic AI tools — no external LLM or API key required.

• Modular, enterprise-grade architecture with a full unit-test suite (Vitest).

Related MCP server: snow-mcp

Project Structure

src/
├── clients/
│   └── servicenowClient.ts   # Axios wrapper: GET/POST/PATCH, auth, retry, timeout, Table API helpers
├── config/
│   └── env.ts                # Zod-validated environment configuration
├── schemas/
│   └── index.ts              # Zod input schemas for every tool
├── services/
│   ├── incidentService.ts    # incident reads/writes + journal (comments/work notes)
│   ├── userService.ts        # sys_user lookups
│   ├── cmdbService.ts        # cmdb_ci search
│   ├── knowledgeService.ts   # kb_knowledge search
│   ├── aiService.ts          # rule-based classification, routing, summaries
│   └── index.ts              # service container
├── tools/
│   ├── phase1.read.ts        # get_incident, search_incidents, get_user, search_cmdb, get_knowledge_article
│   ├── phase2.actions.ts     # create_incident, update_incident, assign_incident, close_incident
│   ├── phase3.ai.ts          # classify_incident, incident_summary, suggest_assignment_group
│   ├── helpers.ts            # response builders + central error handling
│   └── index.ts              # registers all tools
├── types/
│   └── servicenow.ts         # shared TypeScript interfaces
├── utils/
│   ├── logger.ts             # structured logger + redaction
│   ├── errors.ts             # ServiceNowError + safe message mapping
│   └── format.ts             # raw ServiceNow record → clean object mappers
├── server.ts                 # builds the MCP server (config → client → services → tools)
└── index.ts                  # entrypoint (stdio transport)
tests/                        # Vitest unit tests

Setup

Prerequisites

• Node.js 18+

• A ServiceNow instance and an account with Table API access.

Install & build

npm install
cp .env.example .env      # then edit .env with your instance + credentials
npm run build

Configure environment

Run

npm start          # run the built server (dist/index.js)
npm run dev        # run from TypeScript with hot reload

The server speaks MCP over stdio.

Tool Reference

Phase 1 — Read

Phase 2 — Actions

Phase 3 — AI-powered (deterministic, rule-based)

Classification Logic

classify_incident mirrors ServiceNow's Impact × Urgency → Priority matrix. It infers impact from the scope of the issue and urgency from time-critical language, both via documented keyword rules (case-insensitive, first match wins).

Time-critical words (urgent, critical, outage, down, blocked, cannot work, production, emergency, …) escalate urgency → 1, and priority is recomputed from the matrix:

 Impact \ Urgency   1    2    3
        1          P1   P2   P3
        2          P2   P3   P4
        3          P3   P4   P4

suggest_assignment_group uses a keyword→group routing table (VPN/network → Network Operations, email/Outlook → Messaging & Collaboration, password/login → Identity & Access Management, database/SQL → Database Team, laptop/printer → Desktop Support, phone/call forwarding → Telephony, application/crash → Application Support), defaulting to Service Desk.

These rules live in src/services/aiService.ts and are easy to tune for your org's groups.

Sample MCP Client Configuration

Add the server to your MCP client config. Use absolute paths and supply credentials via env.

Claude Desktop (claude_desktop_config.json) / Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "servicenow": {
      "command": "node",
      "args": ["/absolute/path/to/servicenow-mcp/dist/index.js"],
      "env": {
        "SNOW_INSTANCE": "https://dev12345.service-now.com",
        "SNOW_USERNAME": "admin",
        "SNOW_PASSWORD": "your-password",
        "LOG_LEVEL": "info"
      }
    }
  }
}

Run npm run build first so dist/index.js exists.

Testing & Quality

npm test            # run the unit test suite (Vitest)
npm run test:coverage
npm run typecheck   # tsc --noEmit
npm run lint        # eslint

Tests are fully offline — the ServiceNow client is mocked, and the AI tools are deterministic.

Manual smoke test with MCP Inspector

npm run build
npx @modelcontextprotocol/inspector node dist/index.js

Then list tools and try classify_incident / suggest_assignment_group (work offline) or a read tool against your instance.

Security

• Credentials are read only from environment variables; .env is git-ignored.

• The logger redacts any password / authorization / token / secret field, and logs go to stderr only (keeping the MCP stdout channel clean).

• All HTTP requests use a configurable timeout and retry transient failures with exponential backoff; 4xx errors (other than 429) fail fast with safe messages.

License

MIT