SN-MCP-Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@SN-MCP-Server Show me the schema for the incident table"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
๐ 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_explaintool is registered whennow-sdkis 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_docssearches the ServiceNowDocs repo, returnsfile_path/raw_urlfor direct reads, and can resolve the selected branch when a non-default version is requested
Related MCP server: @onlyflows/servicenow-mcp
๐ Quick Start
Option A โ npx (no install needed)
npx @imjaineel-dev/sn-mcp-server --config ./sn-instance.jsonOption 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
Field | Required | Description |
| โ | Short name used in tool calls ( |
| โ | Subdomain ( |
| optional |
|
| optional | Human-friendly display name |
| optional | Use either a top-level |
Basic Auth (auth: "basic")
Field | Required | Description |
| โ | Service account username |
| โ | Password or API token |
OAuth 2.0 (auth: "oauth2")
Field | Required | Description |
| โ |
|
| โ | OAuth application credentials |
| conditional | Required for |
| conditional | Required for |
| conditional | Required for |
| optional | Optional issuer value for |
| optional | Override the default token endpoint (default: |
Default selection is resolved in this order:
explicit top-level
"default"alias in the config objectan entry with
"default": truethe 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
.envfile is loaded automatically at startup.
Variable | Description | Default |
| Path to | Auto-resolved |
| Set to |
|
| IANA timezone for log timestamps ( |
|
| Override log file directory | OS temp folder |
| GitHub Personal Access Token for | none |
CLI flags are also supported as an alternative to environment variables:
--config <path>โ setsSN_INSTANCE_CONFIG--verboseโ setsSN_MCP_VERBOSE=true--github-token <token>โ setsGITHUB_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.logStored in the OS temp directory:
OS | Default log location |
Windows |
|
macOS |
|
Linux |
|
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.json2 knowledge tools โ instance-independent tools for docs and SDK guidance
14 instance tools
Tool | Description | Visibility |
| List all configured instances and their aliases, labels, and URLs. | Visible when |
| Test connectivity to a specific instance or the default instance. | Visible when |
| Query users, groups, and group membership from identity tables. | Visible when |
| Inspect table schema or search for matching tables by name/label. | Visible when |
| Run aggregate queries such as count, sum, avg, min, and max. | Visible when |
| Generic read from any ServiceNow table with encoded queries, fields, paging, and display values. | Visible when |
| Resolve and fetch a record by sys_id, record number, task table, or CMDB CI class. | Visible when |
| Fetch attachment metadata or file content from the Attachment API. | Visible when |
| List update sets or drill into the files inside a specific update set. | Visible when |
| Search scripting artifacts using the native ServiceNow Code Search API. | Visible when |
| Fetch Script Includes, Business Rules, Client Scripts, UI Actions, Scheduled Jobs, Fix Scripts, and Scripted REST artifacts. | Visible when |
| Search classic workflow activity variable values and resolve the owning workflow versions. | Visible when |
| Fetch legacy workflow artifacts from wf_* tables. | Visible when |
| Fetch Workflow Studio and Flow Designer artifacts from sys_hub_* and related tables. | Visible when |
2 knowledge tools
Tool | Description | Visibility |
| Search, browse, and read ServiceNowDocs markdown by release branch. Search mode returns | Always visible. |
| Query the ServiceNow SDK for explanations of SDK skills, APIs, and concepts via | Visible only when |
Runtime visibility rules
Instance tools (14) are hidden when the server starts in config-less mode (no
sn-instance.jsonprovided). In that mode, only the 2 knowledge tools remain visible.sn_read_docsis always registered, because it does not depend on ServiceNow instance credentials.sn_sdk_explainis added only after a successful probe ofnow-sdk; if the package is not installed or cannot be executed, the tool is omitted entirely. Install it globally with:npm install -g now-sdkEvery instance tool accepts an optional
instanceparameter. 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
{
"tool": "sn_aggregate_table",
"table": "incident",
"aggregates": [{ "field": "priority", "function": "count" }],
"group_by": ["priority"]
}๐ Project Structure
SN-MCP-Server/
โโโ src/
โ โโโ cli.js โ npx entrypoint (--config, --verbose, --github-token, --help)
โ โโโ index.js โ server bootstrap and startup banner
โ โโโ config.js โ config path resolution and validation
โ โโโ validator.js โ sn-instance.json schema validation
โ โโโ constants.js โ shared repo/example URLs
โ โโโ env-loader.js โ .env file parser (no external deps)
โ โโโ logger.js โ structured logger, per-run log files
โ โโโ multi-client.js โ multi-instance routing and default-instance resolution
โ โโโ sn-client.js โ per-instance REST client
โ โโโ handler.js โ tool name โ method router
โ โโโ tools.js โ MCP tool definitions
โ โโโ docs-client.js โ ServiceNowDocs search/browse/read implementation
โ โโโ sdk-client.js โ ServiceNow SDK availability probe and explain helper
โโโ scripts/
โ โโโ dev.js โ development helper
โ โโโ inspect.js โ MCP Inspector launcher with origin allowlist
โโโ sn-instance.json โ your credentials (git-ignored)
โโโ sn-instance.example.json โ template with supported auth flows
โโโ .env.example โ environment variable documentation
โโโ README.md โ full project documentation
โโโ package.jsonโ ๏ธ Troubleshooting
Invalid credentials
Verify username/password in
sn-instance.jsonEnsure the account has REST API access enabled in ServiceNow
Instance unreachable
Check the
instancevalue format โ subdomain or full URLVerify VPN / network connectivity
sn-instance.json validation error
The server prints a specific error message pointing to the exact field/entry
See the example: sn-instance.example.json
MCP client not detecting server
Always use absolute paths in MCP client config
Restart the MCP client after config changes
๐ Security Notes
sn-instance.jsonis in.gitignoreโ never commit itUse a dedicated read-only service account per instance
PDI instances can use
admincredentials safely since they're isolatedDo not store credentials in environment variables in shared environments
๐ค Contributing
PRs welcome! Please open an issue first for larger changes.
๐ Report a bug
If you hit a bug, please open a GitHub issue here:
Include the following in your report so it can be fixed quickly:
what you expected to happen
what actually happened
the command or MCP client configuration you used
the relevant log output or error text
any redacted snippets from
sn-instance.jsonor.env
๐ License
See LICENSE for details.
Available Tools
1 toolsn_read_docsA
Access the official ServiceNow AI Platform documentation from https://github.com/ServiceNow/ServiceNowDocs โ pure markdown, optimised for LLM use.
IMPORTANT: Never fetch servicenow.com/docs โ it is a JS SPA with no readable content.
Three execution modes: get_index โ Fetch llms.txt (full release index) so you can study the layout and navigate on your own. Pass 'publication' to drill into one area's TOC. search โ Pass a keyword to find relevant topics across all publications and supplement the results with GitHub code search in the ServiceNowDocs repo. Returns file_url and file_path values ready for get_file. get_file โ Directly read any doc file when you know the path or URL (after reading an index or following a relative markdown link).
Version resolution (fully dynamic โ zero hard-coded branch names): โข Pass 'version' with a release name (e.g. 'Xanadu', 'Zurich', 'Australia'). โข Default branch is fetched live from GitHub API โ always correct, zero maintenance. โข Valid branches come from llms_template.txt in the repo โ the authoritative list. โข Matching is case-insensitive and fuzzy against that live list. โข Unknown/mistyped versions fall back to the default branch with a clear notice.
Recommended workflow:
mode='get_index' โ understand what's available
mode='get_index', publication='api-reference' โ browse a specific area
mode='get_file', file_url='<url from step 2>' โ read the doc OR: mode='search', search='GlideRecord' โ find topics by keyword
Inputs: mode, search, version, file_url, +3 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogโฆ
TDQS
Scored across 1 tool
There is only one tool, so there is no ambiguity between tools. The tool's internal modes (get_index, search, get_file) are clearly distinct and well-documented.
The single tool name 'sn_read_docs' follows a clear verb_noun pattern with a consistent prefix. Since there are no other tools, consistency is trivially maintained.
With only one tool, the server is at the lower edge of what is typically appropriate. The tool is multi-functional and covers multiple operations, but a single tool still feels thin for a docs server.
The tool provides a complete workflow for accessing ServiceNow documentation: index browsing, keyword search, and direct file retrieval, with dynamic version resolution. There are no obvious gaps for a read-only docs access server.
Maintenance
Related MCP Connectors
Read-only MCP access to a documented IT fleet: state, changes, posture. 15 tools.
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
2,000+ MCP servers read at source level. Know what one does before you connect. Free, no key.
Find, document and execute authenticated API calls across 1000+ apps via one MCP server
Related MCP Servers
- AlicenseNot gradedqualityAmaintenanceA metadata-driven MCP server that auto-generates 480+ tools across 160+ ServiceNow tables, with multi-instance support, natural language search, and local script development.336 npm55Apache 2.0
- AlicenseAqualityBmaintenanceThe most comprehensive ServiceNow MCP server. 17 tools for full CRUD, CMDB graph traversal, background scripts, ATF testing, and more.242,047 npm13MIT
- AlicenseNot gradedqualityDmaintenanceMCP server to interact with ServiceNow instances, enabling ITSM, CMDB, workflow, and knowledge search operations.MIT
- FlicenseNot gradedqualityDmaintenanceMCP server providing CRUD tools for ServiceNow business rules, client scripts, and script includes.-