ServiceNow Incident 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).

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

Variable	Required	Default	Description
SNOW_INSTANCE	yes	—	Instance base URL, e.g. https://dev123.service-now.com
SNOW_USERNAME	yes	—	Basic auth username
SNOW_PASSWORD	yes	—	Basic auth password
SNOW_TIMEOUT_MS	no	30000	Per-request timeout (ms)
SNOW_MAX_RETRIES	no	3	Retry attempts on network/429/5xx errors
SNOW_DEFAULT_LIMIT	no	10	Default result count for search tools
LOG_LEVEL	no	info	debug | info | warn | error

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

Tool	Input	Returns
get_incident	{ incidentNumber }	Number, state, priority, assignment group, assignee, descriptions, timestamps
search_incidents	{ assignedTo?, caller?, priority?, state?, limit? }	Matching incidents (newest first)
get_user	{ userName }	User name, email, phone, title, department
search_cmdb	{ name, limit? }	Matching CMDB CIs
get_knowledge_article	{ keyword, limit? }	Matching published KB articles

Phase 2 — Actions

Tool	Input	Effect
create_incident	{ shortDescription, description?, callerId?, assignmentGroup?, impact?, urgency? }	Creates an incident → { incidentNumber, sysId }
update_incident	{ incidentNumber, workNote?, comment? }	Appends work note / comment
assign_incident	{ incidentNumber, assignmentGroup?, assignedTo? }	Updates assignment
close_incident	{ incidentNumber, closeNotes, closeCode? }	Resolves & closes the incident

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

Tool	Input	Returns
classify_incident	{ issue }	{ impact, urgency, priority, reason }
incident_summary	{ incidentNumber }	Executive summary built from the incident + journal
suggest_assignment_group	{ issue }	{ assignmentGroup, reason }

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).

Scope detected in the issue text	Impact	Urgency	Priority
Entire office / company / site / everyone	1	1	P1
Entire team / department / group / floor	2	2	P2
Single employee / one user / "my…"	3	2	P3
Minor / cosmetic / typo / question / slow	3	3	P4
Unrecognized (default)	3	3	P3

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