Who Is This For?

Why servicenow-mcp

Quick Links

Module Coverage

Domain modules covering the full ServiceNow platform:

Authentication

Two authentication methods are supported:

For OAuth setup in ServiceNow, see docs/SERVICENOW_OAUTH_SETUP.md.

Permission System

A five-tier permission model keeps your instance safe by default:

Role-Based Tool Packages

Set MCP_TOOL_PACKAGE to expose only the tools relevant to each persona:

Getting Started

Option A — Interactive Setup Wizard (Recommended)

# Install globally (Node.js 20+ required)
npm install -g @aartiq/servicenow-mcp

# Run the wizard — detects your AI clients and writes config automatically
npx @aartiq/servicenow-mcp setup

The wizard will:

1. Ask for your ServiceNow instance URL + credentials
2. Test the connection
3. Let you pick a tool package and permission level
4. Detect Claude Desktop, Cursor, VS Code, Windsurf, Continue.dev, Claude Code on your machine
5. Write the config directly — no copy-paste, no manual JSON editing

# Add a second instance later
servicenow-mcp setup --add

# Manage instances
servicenow-mcp instances list

Option B — Manual Setup

git clone https://github.com/aartiq/servicenow-mcp.git && cd servicenow-mcp
npm install && npm run build
cp .env.example .env   # fill in your ServiceNow credentials

Then point your AI client at dist/server.js — see Supported AI Clients below.

No ServiceNow instance? Get a free Personal Developer Instance at developer.servicenow.com — ready in minutes.

Full installation guide → docs/INSTALLATION.md

Client Setup Guides

Step-by-step setup for every major AI client — Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Zed, GitHub Copilot, Continue.dev, Cline, JetBrains, Amazon Q, Google AI Studio, ChatGPT, Grok, Ollama, and more.

Full guide → docs/CLIENT_SETUP.md

For quick setup snippets, see the Supported AI Clients section below.

Example Interactions

Once connected, ask your AI assistant in plain language:

ITSM & Change Management:

Show me all open P1 incidents assigned to the Network Operations group.

Create a normal change request for deploying the new API gateway — implementation planned for Saturday midnight.

What CMDB CIs does the ERP application depend on?

Scripting & Development:

List all client scripts on the incident table and show me the ones that fire on form load.

Create a UI action button "Escalate to L3" on the incident form that assigns the ticket to the L3-Support group.

Show me all ACL rules for the change_request table that restrict the "delete" operation.

Service Portal & UI Builder:

List all widgets in the Service Portal that contain "catalog" in their name.

Get the full source code of the "Stock Ticker" widget so I can update its server script.

Create a new portal widget called "My Approvals Widget" with a simple Angular template that lists pending approvals.

Integrations & Events:

List all REST Message definitions that connect to external APIs.

Show me all transform maps that target the incident table.

Fire the custom event "myapp.ticket.escalated" on incident INC0012345.

For 120+ real-world examples with inputs, outputs, and advanced workflows, see EXAMPLES.md.

Slash Commands & @ Mentions

Once connected, type / in Claude Desktop or Cursor to see built-in ServiceNow shortcuts:

Type @ to pull live ServiceNow data into your AI context:

Add your own commands in servicenow-mcp.commands.json:

[
  {
    "name": "my-p1-runbook",
    "description": "P1 runbook for my team",
    "template": "List all P1 incidents in the Network category. For each: number, description, assignee, time open. Flag SLA breaches."
  }
]

Advanced Configuration

Supported AI Clients

Any MCP-compatible AI works. servicenow-mcp has been tested with every major AI assistant, editor, and agent framework. Pick yours and follow the 3-step setup below.

AI Assistants & Chat

{
  "mcpServers": {
    "servicenow-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/servicenow-mcp/dist/server.js"],
      "env": {
        "SERVICENOW_INSTANCE_URL": "https://yourinstance.service-now.com",
        "SERVICENOW_AUTH_METHOD": "basic",
        "SERVICENOW_BASIC_USERNAME": "admin",
        "SERVICENOW_BASIC_PASSWORD": "your_password",
        "WRITE_ENABLED": "false"
      }
    }
  }
}

{
  "mcpServers": {
    "servicenow-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/servicenow-mcp/dist/server.js"],
      "env": {
        "SN_INSTANCES_CONFIG": "/absolute/path/to/instances.json"
      }
    }
  }
}

from openai import OpenAI
import os, subprocess

# Start servicenow-mcp as a subprocess MCP server
proc = subprocess.Popen(
    ["node", "/path/to/servicenow-mcp/dist/server.js"],
    stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE,
    env={**os.environ,
         "SERVICENOW_INSTANCE_URL": "https://yourinstance.service-now.com",
         "SERVICENOW_AUTH_METHOD": "basic",
         "SERVICENOW_BASIC_USERNAME": "admin",
         "SERVICENOW_BASIC_PASSWORD": "your_password"}
)

client = OpenAI()
response = client.responses.create(
    model="gpt-4o",
    tools=[{"type": "mcp", "server_label": "servicenow-mcp"}],
    input="Show me all open P1 incidents"
)

pip install google-generativeai
python clients/gemini/servicenow_gemini_client.py

AI Code Editors

{
  "mcpServers": {
    "servicenow-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/servicenow-mcp/dist/server.js"],
      "env": {
        "SERVICENOW_INSTANCE_URL": "https://yourinstance.service-now.com",
        "SERVICENOW_AUTH_METHOD": "basic",
        "SERVICENOW_BASIC_USERNAME": "admin",
        "SERVICENOW_BASIC_PASSWORD": "your_password",
        "WRITE_ENABLED": "true",
        "SCRIPTING_ENABLED": "true"
      }
    }
  }
}

{
  "context_servers": {
    "servicenow-mcp": {
      "command": { "path": "node", "args": ["/path/to/servicenow-mcp/dist/server.js"] },
      "settings": {
        "SERVICENOW_INSTANCE_URL": "https://yourinstance.service-now.com",
        "SERVICENOW_AUTH_METHOD": "basic",
        "SERVICENOW_BASIC_USERNAME": "admin",
        "SERVICENOW_BASIC_PASSWORD": "your_password"
      }
    }
  }
}

IDE Extensions

{
  "servers": {
    "servicenow-mcp": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/servicenow-mcp/dist/server.js"],
      "env": {
        "SERVICENOW_INSTANCE_URL": "https://yourinstance.service-now.com",
        "SERVICENOW_AUTH_METHOD": "basic",
        "SERVICENOW_BASIC_USERNAME": "admin",
        "SERVICENOW_BASIC_PASSWORD": "your_password",
        "WRITE_ENABLED": "true",
        "SCRIPTING_ENABLED": "true"
      }
    }
  }
}

{
  "servers": {
    "servicenow-mcp": {
      "type": "stdio",
      "command": "node",
      "args": ["${workspaceFolder}/../../servicenow-mcp/dist/server.js"],
      "env": {
        "SERVICENOW_INSTANCE_URL": "https://yourinstance.service-now.com",
        "SERVICENOW_AUTH_METHOD": "basic",
        "SERVICENOW_BASIC_USERNAME": "admin",
        "SERVICENOW_BASIC_PASSWORD": "your_password"
      }
    }
  }
}

{
  "mcpServers": [
    {
      "name": "servicenow-mcp",
      "command": "node",
      "args": ["/path/to/servicenow-mcp/dist/server.js"],
      "env": {
        "SERVICENOW_INSTANCE_URL": "https://yourinstance.service-now.com",
        "SERVICENOW_AUTH_METHOD": "basic",
        "SERVICENOW_BASIC_USERNAME": "admin",
        "SERVICENOW_BASIC_PASSWORD": "your_password"
      }
    }
  ]
}

{
  "mcpServers": {
    "servicenow-mcp": {
      "command": "node",
      "args": ["/path/to/servicenow-mcp/dist/server.js"],
      "env": {
        "SERVICENOW_INSTANCE_URL": "https://yourinstance.service-now.com",
        "SERVICENOW_AUTH_METHOD": "basic",
        "SERVICENOW_BASIC_USERNAME": "admin",
        "SERVICENOW_BASIC_PASSWORD": "your_password"
      }
    }
  }
}

CLI & Terminal Agents

# Install Claude Code
npm install -g @anthropic-ai/claude-code

# Register servicenow-mcp as an MCP server
claude mcp add servicenow-mcp node /absolute/path/to/servicenow-mcp/dist/server.js \
  --env SERVICENOW_INSTANCE_URL=https://yourinstance.service-now.com \
  --env SERVICENOW_AUTH_METHOD=basic \
  --env SERVICENOW_BASIC_USERNAME=admin \
  --env SERVICENOW_BASIC_PASSWORD=your_password

# Verify
claude mcp list

# Use it
claude "Show me all unresolved P1 incidents"

Quick Reference

What's New in v1.0

Initial public release of servicenow-mcp — 400+ ServiceNow MCP tools, full CLI, multi-instance support, and 14 role-based tool packages. See CHANGELOG.md for details.

Documentation

Development

npm install          # install dependencies
npm run build        # compile TypeScript → dist/
npm test             # run unit tests
npm run dev          # watch mode (hot reload)
npm run type-check   # TypeScript type check only
npm run lint         # lint

Project Structure

src/
  server.ts              — MCP server entry point (stdio)
  servicenow/
    client.ts            — ServiceNow REST API client (Basic / OAuth / per-user)
    instances.ts         — Multi-instance manager
    types.ts             — TypeScript type definitions + AuthMode
  tools/
    index.ts             — Tool router & role-based package system
    core.ts, incident.ts, change.ts, problem.ts, task.ts
    knowledge.ts, catalog.ts, user.ts, reporting.ts, atf.ts
    now-assist.ts, script.ts, agile.ts, hrsd.ts, csm.ts
    security.ts, flow.ts, portal.ts, integration.ts, notification.ts
    performance.ts, sys-properties.ts, updateset.ts, va.ts, itam.ts, devops.ts
  prompts/
    index.ts             — MCP prompts registry (/ slash commands)
    itsm.ts              — 11 built-in slash commands
    user-prompts.ts      — Custom commands from servicenow-mcp.commands.json
  resources/
    index.ts             — MCP resources (@ mentions)
  cli/
    index.ts             — CLI entry point (commander.js)
    setup.ts             — Interactive setup wizard
    detect-clients.ts    — Auto-detect installed AI clients
    config-store.ts      — ~/.config/servicenow-mcp/instances.json
    auth.ts              — servicenow-mcp auth login/logout/whoami
    writers/index.ts     — Write configs to AI client config files
  utils/
    permissions.ts       — Five-tier permission gate functions
    errors.ts            — Typed error classes
    logging.ts           — Structured logger
tests/
  tools/                 — Unit tests
docs/                    — Reference documentation
clients/
  claude-desktop/        — Claude Desktop setup guide
  cursor/                — Cursor setup guide
  vscode/                — VS Code setup guide
  claude-code/           — Claude Code setup guide
  codex/                 — OpenAI Codex Python client
  gemini/                — Google Gemini Python client
smithery.yaml            — Smithery registry config

Contributing

Contributions are welcome. Please read CONTRIBUTING.md before opening a pull request.

• Bug reports and feature requests: open an issue
• New tool domains, additional tests, or documentation improvements are especially appreciated
• All PRs require npm test to pass

Security

If you discover a security vulnerability, please follow the responsible disclosure process in SECURITY.md. Do not open a public issue.

Frequently Asked Questions

Do I need to know the ServiceNow API to use this?
No. For beginners, you just connect your AI and ask questions in plain English. The server handles all API calls automatically.

Which ServiceNow versions are supported?
All actively supported ServiceNow releases. The server targets the latest available APIs and has been tested on the three most recent releases.

Can I use this on a free Personal Developer Instance (PDI)?
Yes. Get a free PDI at developer.servicenow.com and connect in 5 minutes.

Is it safe to use on production?
Yes. The permission system is read-only by default. Write, scripting, and Now Assist capabilities must each be explicitly enabled with environment variables. Use role packages to limit the tool surface.

Does it support multi-instance / multiple customers?
Yes. Configure any number of instances (prod, staging, dev, or multiple customer tenants) via instances.json or environment variables. Use list_instances, switch_instance, and get_current_instance tools to manage them, or pass instance: "name" to any individual tool call. See docs/MULTI_INSTANCE.md.

Is it free?
Completely free and open-source under the MIT license.

License

MIT — free for personal and commercial use.