📘 SN-MCP-Server

A read-only Model Context Protocol (MCP) server for ServiceNow — built for developers, AI workflows, and tools that need deep visibility into ServiceNow across multiple instances (Prod, Dev, Test, PDI).

✨ Features

• 🔗 Multi-instance — Prod, Dev, Test, PDI in one server
• 🔍 Powerful querying — Table, Aggregate, Code Search APIs
• 🧠 Intelligent record resolution — INC, CHG, RITM, sys_id
• 🔄 Flow Designer + Legacy Workflows
• 🧩 Schema inspection & discovery
• 👥 Identity & access data
• 🔑 Multiple Auth Methods — Basic Auth and OAuth 2.0 (Client Credentials, Password, Auth Code, JWT)
• 🧰 ServiceNow SDK support — optional sn_sdk_explain tool is registered when now-sdk is installed globally (npm install -g now-sdk)
• Read-only by design — safe on production instances
• 📄 Per-run log files — one file per server start, stored in OS temp folder
• 🔬 Verbose tool logging — per-call called/received debug lines (instance, args, result summary) when SN_MCP_VERBOSE=true
• 📚 ServiceNow Docs search — sn_read_docs searches the ServiceNowDocs repo, returns file_path/raw_url for direct reads, and can resolve the selected branch when a non-default version is requested

🚀 Quick Start

Option A — npx (no install needed)

npx @imjaineel-dev/sn-mcp-server --config ./sn-instance.json

Option B — Local clone

git clone https://github.com/ImJaineel/SN-MCP-Server.git
cd SN-MCP-Server
npm install
npm start   # auto-detects sn-instance.json in repo root

⚙️ Configuration

1. Create sn-instance.json

{
  "default": "dev",
  "instances": [
    {
      "alias": "prod",
      "label": "Production",
      "instance": "mycompany-prod",
      "auth": "oauth2",
      "grant_type": "client_credentials",
      "client_id": "your-client-id",
      "client_secret": "your-client-secret"
    },
    {
      "alias": "dev",
      "label": "Development",
      "instance": "mycompany-dev",
      "auth": "basic",
      "username": "svc_mcp_readonly",
      "password": "your-password-here"
    }
  ]
}

📄 Full example: sn-instance.example.json

Common fields

Basic Auth (auth: "basic")

OAuth 2.0 (auth: "oauth2")

Default selection is resolved in this order:

1. explicit top-level "default" alias in the config object
2. an entry with "default": true
3. the first entry in the list

2. Environment variables (optional)

All optional — set them in your shell, in the MCP client "env" block, or in a .env file at the project root. Values from the shell take precedence over .env.

Note: If you are running the server from a local clone, a root-level .env file is loaded automatically at startup.

CLI flags are also supported as an alternative to environment variables:

• --config <path> → sets SN_INSTANCE_CONFIG
• --verbose → sets SN_MCP_VERBOSE=true
• --github-token <token> → sets GITHUB_TOKEN

🔌 MCP Client Setup

For Anyone, Everyone

VS Code: Press Ctrl+Shift+P, select Add MCP

Claude Desktop: Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows)

Gemini Code Assist: Create or edit ~/.gemini/mcp.json

Amazon Q: Create or edit ~/.aws/amazonq/mcp.json

Using npx (recommended):

{
  "mcpServers": {
    "servicenow": {
      "command": "npx",
      "args": ["sn-mcp-server", "--config", "/absolute/path/to/sn-instance.json"],
    }
  }
}

Using local clone:

{
  "mcpServers": {
    "servicenow": {
      "command": "node",
      "args": ["/absolute/path/to/SN-MCP-Server/src/index.js"]
    }
  }
}

⚠️ Always use absolute paths in MCP client configs.

▶️ Running locally

# Standard start (auto-detects ./sn-instance.json)
npm start

# With explicit config path
node src/index.js --config /path/to/sn-instance.json

# With verbose logging
npm run dev
node src/index.js --config ./sn-instance.json --verbose

# Auto-restart on file changes (development)
npm run watch

# Open MCP Inspector UI in browser (test tools interactively)
npm run inspect
# The inspector launcher accepts localhost and 127.0.0.1 origins so the browser can connect reliably.

# Show help
npx sn-mcp-server --help

🪵 Logs

Each server run creates a new timestamped log file:

2026-04-09T14-32-01.123Z.log

Stored in the OS temp directory:

Override with SN_LOG_DIR env var. Log files are cleaned up automatically by the OS on reboot.

The startup banner always prints the exact log file path:

Log file : /tmp/ImJaineel_SN-MCP-Instance_logs/2026-04-09T14-32-01.123Z.log

🧰 Available Tools

The server exposes 16 tools at runtime when the current environment supports them:

• 14 instance tools — require a configured sn-instance.json
• 2 knowledge tools — instance-independent tools for docs and SDK guidance

14 instance tools

2 knowledge tools