SN MCP Server

📘 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 → sets SN_INSTANCE_CONFIG
• --verbose → sets SN_MCP_VERBOSE=true
• --github-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

Runtime visibility rules

• Instance tools (14) are hidden when the server starts in config-less mode (no sn-instance.json provided). In that mode, only the 2 knowledge tools remain visible.
• `sn_read_docs` is always registered, because it does not depend on ServiceNow instance credentials.
• `sn_sdk_explain` is added only after a successful probe of now-sdk; if the package is not installed or cannot be executed, the tool is omitted entirely. Install it globally with: npm install -g now-sdk
• Every instance tool accepts an optional instance parameter. If omitted, the server uses the configured default instance.

---

💡 Usage Examples

Target a specific instance

sn_get_scripted_artifacts  table="sys_script_include"  query="nameLIKEMorpheus"  instance="prod"

sn_query_table table="incident" query="state=1" instance="dev" sn_get_update_sets instance="pdi"

Query incidents

{ "tool": "sn_query_table", "table": "incident", "query": "active=true", "limit": 5 }

Search ServiceNow Docs

{ "tool": "sn_read_docs", "mode": "search", "search": "Install the ServiceNow SDK in an application", "version": "australia" }

Use mode": "get_file" with the returned file_path or raw_url to read the matching doc.

Get record by number

{ "tool": "sn_get_record", "number": "INC0012345" }

Search legacy workflows

{ "tool": "sn_legacy_workflow_search", "query": "morpheus", "instance": "prod" }

Aggregate

`json