servicenow-mcp

The Most Comprehensive ServiceNow MCP Server

400+ tools · 31+ ServiceNow modules · 5-minute setup · MIT licensed · Works with any AI

servicenow-mcp is the most comprehensive, production-ready MCP server for ServiceNow — and the only one that truly does it all.

Connect Claude, ChatGPT, Gemini, Cursor, GitHub Copilot, or any MCP-compatible AI in under 5 minutes. Then let your AI read, build, deploy, and automate across every ServiceNow module — incidents, changes, scripts, flows, portals, integrations, HRSD, CSM, and more.

Ask in plain English. Deploy business rules from chat. Run ATF suites on demand. Query dev, staging, and prod simultaneously. Automate across multiple customer tenants without switching tabs. Your AI, your instance, your rules.

Any AI. Any instance. Any scale. 100% open-source.

Keywords: ServiceNow MCP server · Model Context Protocol · ServiceNow AI · ITSM automation · ServiceNow Claude · ServiceNow ChatGPT · ServiceNow Cursor · ServiceNow Copilot · ServiceNow LLM · ServiceNow agent · MCP tools · ServiceNow API · agentic AI · ServiceNow developer tools

Beginners	Zero ServiceNow API knowledge needed. Connect in 5 minutes. Ask in plain English. Free PDI at developer.servicenow.com.
Developers	Write, deploy, test, and manage scripts, flows, widgets, and integrations at AI speed — 10x faster.
Architects & MSPs	Orchestrate multi-step autonomous workflows. Compare environments. Manage multiple customer tenants in one session.

---

Who Is This For?

Beginners

Zero ServiceNow API knowledge required.

Connect Claude Desktop or Cursor to your free PDI in 5 minutes. Ask questions in plain English, browse incidents, search KB articles, place catalog orders, monitor SLAs — all from your AI chat window. No code. No Postman. No documentation diving. Just ask.

Start here → 5-Minute Quickstart

Developers

10x faster with AI as your development partner.

Write business rules, deploy client scripts, manage UI Policies and ACLs, create Service Portal widgets, configure REST Messages, manage Transform Maps, and update changesets — all in plain English. Full TypeScript types, ATF integration, and role-based packages built in.

Explore → Platform Developer Package

Architects, Admins & MSPs

Autonomous workflows. Multi-instance. Multi-customer.

Trigger Agentic Playbooks, orchestrate multi-step ITSM/HRSD/CSM processes, compare environments side by side, manage dozens of customer tenants in one session, and run full data quality audits — at AI speed, across your entire ServiceNow estate.

Deep dive → Now Assist & Agentic Guide

---

Why servicenow-mcp

Fully Autonomous AI Operations

Your AI doesn't just answer questions — it acts. Create incidents, write and deploy scripts, trigger flows, fire events, upload attachments, manage changesets, and run full ATF suites — end-to-end, without manual steps. Native Now Assist Agentic Playbook support for next-generation ServiceNow AI automation.

Works With Every AI, Out of the Box

Claude, ChatGPT, Gemini, Grok, Cursor, Windsurf, GitHub Copilot, Amazon Q, JetBrains, Continue.dev, Cline, Zed, Google AI Studio, Ollama — all supported out of the box. Any MCP-compatible client. Any custom Python or TypeScript agent. One server, every AI platform, zero lock-in.

Unmatched Platform Coverage

400+ production-ready tools across every ServiceNow domain — ITSM, ITOM, HRSD, CSM, SecOps, GRC, Agile, ATF, Flow Designer, Scripting, Now Assist, Service Portal, Integration Hub, Performance Analytics, System Properties, Update Sets, Virtual Agent, ITAM, DevOps, Machine Learning, Workspace/UIB, Mobile, and Deployment. Nothing else comes close.

Role-Based Tool Intelligence

Fourteen pre-built persona packages — service desk, platform developer, portal developer, integration engineer, ITOM engineer, AI developer, ITAM analyst, DevOps engineer, and more. Each exposes exactly the right tools for that role. Reduce noise, enforce least-privilege, and configure once per team.

Safe by Default, Powerful When Needed

A five-tier permission model keeps your instance protected. Read is always on. Write, CMDB, Scripting, Now Assist, and ATF capabilities each require an explicit opt-in flag. No AI can accidentally modify your production data. Scale permissions as your confidence grows — without touching code.

True Multi-Instance & Multi-Customer

Connect to unlimited ServiceNow instances from one session — dev, staging, prod, and multiple customer tenants simultaneously. Pass instance: "acme_prod" on any tool call, or switch_instance globally. MSPs, consultants, and enterprise teams can compare, query, and automate across every environment at once. No other ServiceNow MCP server does this.

---

Quick Links

Resource	Link
All Tools Reference	docs/TOOLS.md
Client Setup (All AI tools, beginner + advanced)	docs/CLIENT_SETUP.md
Role-Based Tool Packages	docs/TOOL_PACKAGES.md
Now Assist & AI Integration	docs/NOW_ASSIST.md
ATF Testing Guide	docs/ATF.md
Scripting Management	docs/SCRIPTING.md
Reporting & Analytics	docs/REPORTING.md
Multi-Instance Setup	docs/MULTI_INSTANCE.md
120+ Real-World Examples	EXAMPLES.md
Changelog	CHANGELOG.md

---

Module Coverage

Domain modules covering the full ServiceNow platform:

Module	Key Capabilities
Core & CMDB	Record query, schema discovery, CMDB CIs, ITOM Discovery, MID Servers, multi-instance management
Incident Management	Create, update, resolve, close, work notes, comments
Problem Management	Problem records, root cause analysis, known errors
Change Management	Create, get, update, submit for approval, close change requests
Task Management	Generic tasks, my-task lists, completions
Knowledge Base	Search, create, update, publish KB articles
Service Catalog & Approvals	Catalog browsing, create/update items, order items, SLA tracking, approval workflows, approval rules
User & Group Management	Users, groups, membership, role assignments
Reporting & Analytics	Aggregate queries, trend analysis, create/update reports, scheduled job CRUD, run history
ATF Testing	Test suites, test execution, ATF Failure Insight
Now Assist / AI	NLQ, AI Search, summaries, resolution suggestions, Agentic Playbooks
Scripting	Business rules, script includes, client script CRUD, UI Policies, UI Actions, ACL management, changesets
Agile / Scrum	Stories, epics, sprints, scrum tasks
HR Service Delivery (HRSD)	HR cases, HR services, employee profiles, onboarding/offboarding
Customer Service Management (CSM)	Customer cases, accounts, contacts, products, SLAs
Security Operations & GRC	SecOps incidents, vulnerabilities, GRC risks, controls, threat intel
Flow Designer & Process Automation	Flows, subflows, triggers, executions, Process Automation playbooks
Service Portal & UI Builder	Create/list portals & pages, widgets (create/update/deploy), Next Experience apps/pages, themes
Integration Hub	REST Messages, Transform Maps, Import Sets, Event Registry, OAuth apps, credential aliases
Notifications & Attachments	Email notifications, email logs, file attachments (upload/list/delete), templates, subscriptions
Performance Analytics	PA indicators/scorecards, time-series, create/update dashboards, PA jobs, data quality checks
System Properties	Get, set, bulk operations, validate, export/import, audit history
Update Set Management	Create, switch, preview, complete, export, auto-ensure active set
Virtual Agent (VA)	Topic authoring, conversation history, categories, topic listing
IT Asset Management (ITAM)	Assets, software licenses, contracts, compliance reporting
DevOps & Pipeline Tracking	Pipelines, deployments, change governance, DORA metrics
Scoped Applications (App Studio)	List, get, create, and update scoped application records

---

Authentication

Two authentication methods are supported:

Method	Best For
Basic Auth	Development, personal instances, quick setup
OAuth 2.0 (client credentials / password grant)	Production deployments, service accounts

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

---

Permission System

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

Tier	Environment Variable	Covers
0 — Read	(always on)	All query and read operations
1 — Write	WRITE_ENABLED=true	Create/update across ITSM, HRSD, CSM, Agile
2 — CMDB Write	CMDB_WRITE_ENABLED=true	CI create/update in the CMDB
3 — Scripting	SCRIPTING_ENABLED=true	Business rules, script includes, changesets
4 — Now Assist	NOW_ASSIST_ENABLED=true	AI Agentic Playbooks, NLQ, AI Search

---

Role-Based Tool Packages

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

Package	Persona	Tools Included
full	Administrators	All tools (400+)
service_desk	L1/L2 Agents	Incidents, tasks, approvals, KB, SLA
change_coordinator	Change Managers	Changes (create/approve/close), CAB, CMDB, approvals
knowledge_author	KB Authors	Knowledge base create/publish
catalog_builder	Catalog Admins	Catalog, users, groups
system_administrator	Sys Admins	Users, groups, reports, logs, notifications, attachments, ACLs, PA
platform_developer	Developers	Scripts, UI Policies, UI Actions, ACLs, client scripts, ATF, changesets
portal_developer	Portal/UX Devs	Portals, pages, widgets (create/update), UI Policies, UI Actions, client scripts
integration_engineer	Integration Devs	REST Messages, Transform Maps, Import Sets, Events, OAuth, credentials
itom_engineer	ITOM Engineers	CMDB, Discovery, MID servers, events
agile_manager	Scrum Masters	Stories, epics, sprints
ai_developer	AI Builders	Now Assist, NLQ, Agentic Playbooks

---

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:

Command	What it does
/morning-standup	P1/P2 open incidents, changes due today, SLA breaches
/my-tickets	All open tasks/incidents assigned to you
/p1-alerts	Active P1 incidents with time-open and assignee
/my-changes	Your pending change requests and approval status
/create-incident	Guided incident creation
/sla-breaches	Records currently breaching SLA
/ci-health	CMDB CI health check
/run-atf	Trigger ATF test suite
/switch-instance	Interactive instance picker
/knowledge-search	Search KB articles
/deploy-updateset	Guided update set commit

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

Mention	Returns
@my-incidents	Your open incidents
@open-changes	Pending change requests
@sla-breaches	Records breaching SLA now
@instance:info	Current instance metadata
@ci:<name>	CMDB CI by name
@kb:<title>	Knowledge article by title

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

Topic	Guide
OAuth 2.0 setup (ServiceNow OAuth app creation)	docs/SERVICENOW_OAUTH_SETUP.md
Multi-instance / multi-customer (dev, staging, prod, tenants)	docs/MULTI_INSTANCE.md
Role-based tool packages	docs/TOOL_PACKAGES.md
All environment variables reference	docs/INSTALLATION.md

---

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

1. Install Claude Desktop from claude.ai/download
2. Edit config:
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
3. Add this block — single instance (replace path and credentials):

{
  "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"
      }
    }
  }
}

Or use multi-instance (dev + staging + prod, or multiple customer tenants):

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

Copy instances.example.json → instances.json, fill in your instances, then ask:

"List instances" → "Switch to prod" → "Show me all P1 incidents" "Get open changes from customer_acme" (uses instance parameter per-call)

4. Restart Claude Desktop. The hammer icon confirms connection.

Full guide → clients/claude-desktop/SETUP.md | docs/MULTI_INSTANCE.md

OpenAI supports MCP via the Responses API (mcp tool type) in the latest SDK (v1.50+):

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

Full guide → docs/CLIENT_SETUP.md

1. Install servicenow-mcp: npm install -g @aartiq/servicenow-mcp
2. Use the Python client in clients/gemini/:

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

Full guide → clients/gemini/SETUP.md

---

AI Code Editors

1. Open Cursor → Settings → MCP
2. Add server config:

{
  "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"
      }
    }
  }
}

3. Restart Cursor. Ask in Chat: "List all open P1 incidents"

Multi-instance: Replace the env block with "SN_INSTANCES_CONFIG": "/path/to/instances.json" to connect to multiple tenants.

Full guide → clients/cursor/SETUP.md

1. Open Windsurf → Cascade → Configure MCP
2. Add the same JSON block as Cursor above
3. Reload Windsurf window

Full guide → docs/CLIENT_SETUP.md

1. Open Zed → ~/.config/zed/settings.json
2. Add under "context_servers":

{
  "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"
      }
    }
  }
}

Full guide → docs/CLIENT_SETUP.md

---

IDE Extensions

VS Code 1.99 and later includes built-in MCP support — no extension or subscription required.

1. Install VS Code 1.99+
2. Create .vscode/mcp.json in your workspace (or edit User settings):

{
  "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"
      }
    }
  }
}

3. Open the Command Palette (Cmd/Ctrl+Shift+P) → MCP: List Servers to verify the connection
4. Open Copilot Chat (or any AI assistant in VS Code) and use @servicenow-mcp or just ask naturally

Tip: Add .vscode/mcp.json to .gitignore if it contains credentials, or use environment variables from a .env file.

Full guide → clients/vscode/SETUP.md

1. Install VS Code + GitHub Copilot extension
2. Create .vscode/mcp.json in your project:

{
  "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"
      }
    }
  }
}

3. Open Copilot Chat → Agent mode → @servicenow-mcp

Full guide → clients/vscode/SETUP.md

1. Install Continue from VS Code Marketplace
2. Edit ~/.continue/config.json:

{
  "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"
      }
    }
  ]
}

Full guide → docs/CLIENT_SETUP.md

1. Install Cline from VS Code Marketplace
2. Open Cline → MCP Servers → Add Server
3. Enter the path to servicenow-mcp/dist/server.js and your environment variables

Full guide → docs/CLIENT_SETUP.md

1. Install JetBrains AI Assistant plugin
2. Go to Settings → Tools → AI Assistant → MCP Servers
3. Add a new server with the path to servicenow-mcp/dist/server.js
4. Set environment variables in the server configuration dialog

Full guide → docs/CLIENT_SETUP.md

1. Install Amazon Q Developer extension for VS Code or IntelliJ
2. Configure MCP via ~/.aws/amazonq/mcp.json:

{
  "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"
      }
    }
  }
}

Full guide → docs/CLIENT_SETUP.md

---

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"

Full guide → clients/claude-code/SETUP.md

1. Install Ollama and pull a model: ollama pull llama3
2. Use an MCP-compatible client (e.g. Cline or Continue) configured to use Ollama as the model
3. Point the MCP server at servicenow-mcp/dist/server.js

Full guide → docs/CLIENT_SETUP.md

---

Quick Reference

Client	Type	Auth	Guide
Claude Desktop	Desktop app	Basic, OAuth	Setup
Claude Code CLI	Terminal	Basic, OAuth	Setup
Cursor	AI editor	Basic, OAuth	Setup
Windsurf	AI editor	Basic, OAuth	Setup
Zed	AI editor	Basic, OAuth	Setup
VS Code (Native MCP 1.99+)	IDE	Basic, OAuth	Setup
VS Code + GitHub Copilot	IDE	Basic, OAuth	Setup
VS Code + Continue.dev	IDE	Basic, OAuth	Setup
VS Code + Cline	IDE	Basic, OAuth	Setup
JetBrains AI	IDE	Basic, OAuth	Setup
Amazon Q Developer	IDE / CLI	Basic, OAuth	Setup
ChatGPT / OpenAI	API	Basic, OAuth	Setup
Google AI Studio	API / Agent	Basic, OAuth	Setup
Google Gemini API	API	Basic, OAuth	Setup
Grok (xAI)	API	Basic, OAuth	Setup
Ollama (local)	Local	Basic	Setup
Anthropic Agent SDK	Python	Basic, OAuth	Setup

---

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

Guide	Description
docs/TOOLS.md	Complete reference for all tools with parameters, return types, and permission requirements
docs/CLIENT_SETUP.md	Step-by-step beginner + advanced setup for all AI clients
docs/TOOL_PACKAGES.md	Role-based package reference — which tools each of the 14 persona packages includes
docs/NOW_ASSIST.md	Now Assist and AI integration guide — NLQ, AI Search, Agentic Playbooks
docs/ATF.md	ATF testing guide — suites, test runs, ATF Failure Insight
docs/SCRIPTING.md	Scripting management — business rules, script includes, UI Policies, UI Actions, ACLs, changesets
docs/REPORTING.md	Reporting and analytics — aggregate queries, Performance Analytics, scheduled jobs
docs/MULTI_INSTANCE.md	Multi-instance configuration via instances.json or environment variables
docs/SERVICENOW_OAUTH_SETUP.md	Creating an OAuth application in ServiceNow for secure API access
docs/INSTALLATION.md	Full installation guide including environment variables reference
EXAMPLES.md	120+ real-world examples with inputs, outputs, and advanced workflows

---

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.

---

The only ServiceNow MCP server you'll ever need.

400+ tools. 31+ modules. Every AI platform. True multi-instance. Open-source forever.

servicenow-mcp • ServiceNow MCP Server • ServiceNow AI Agent • ServiceNow Claude Integration • ServiceNow ChatGPT • ServiceNow Cursor • ServiceNow Gemini • ServiceNow Automation • ServiceNow Developer Tools • ServiceNow Multi-Instance • ServiceNow MSP

If servicenow-mcp saves you time, please ⭐ star the repository — it helps others find the project.