{
  "markdown": "# 📘 SN-MCP-Server\n\nA **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).\n\n<!-- [![GitHub Package](https://img.shields.io/github/package-json/v/ImJaineel/SN-MCP-Server?label=GitHub%20Packages&logo=github)](https://github.com/ImJaineel/SN-MCP-Server/packages) -->\n[![NPM Package](https://img.shields.io/npm/v/@imjaineel-dev/sn-mcp-server)](https://www.npmjs.com/package/@imjaineel-dev/sn-mcp-server)\n[![Node.js](https://img.shields.io/badge/node-%3E%3D22.0.0-brightgreen)](https://nodejs.org)\n[![License](https://img.shields.io/badge/any_text-Personal_Use_Only-blue?label=License&color=blue)](LICENSE)\n\n---\n\n## ✨ Features\n\n- 🔗 **Multi-instance** — Prod, Dev, Test, PDI in one server\n- 🔍 **Powerful querying** — Table, Aggregate, Code Search APIs\n- 🧠 **Intelligent record resolution** — INC, CHG, RITM, sys_id\n- 🔄 **Flow Designer + Legacy Workflows**\n- 🧩 **Schema inspection & discovery**\n- 👥 **Identity & access data**\n- 🔑 **Multiple Auth Methods** — Basic Auth and OAuth 2.0 (Client Credentials, Password, Auth Code, JWT)\n- 🧰 **ServiceNow SDK support** — optional `sn_sdk_explain` tool is registered when `now-sdk` is installed globally (`npm install -g now-sdk`)\n-  **Read-only by design** — safe on production instances\n- 📄 **Per-run log files** — one file per server start, stored in OS temp folder\n- 🔬 **Verbose tool logging** — per-call called/received debug lines (instance, args, result summary) when `SN_MCP_VERBOSE=true`\n- 📚 **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\n\n---\n\n## 🚀 Quick Start\n\n### Option A — npx (no install needed)\n\n```bash\nnpx @imjaineel-dev/sn-mcp-server --config ./sn-instance.json\n```\n\n### Option B — Local clone\n\n```bash\ngit clone https://github.com/ImJaineel/SN-MCP-Server.git\ncd SN-MCP-Server\nnpm install\nnpm start   # auto-detects sn-instance.json in repo root\n```\n\n---\n\n## ⚙️ Configuration\n\n### 1. Create `sn-instance.json`\n\n```json\n{\n  \"default\": \"dev\",\n  \"instances\": [\n    {\n      \"alias\": \"prod\",\n      \"label\": \"Production\",\n      \"instance\": \"mycompany-prod\",\n      \"auth\": \"oauth2\",\n      \"grant_type\": \"client_credentials\",\n      \"client_id\": \"your-client-id\",\n      \"client_secret\": \"your-client-secret\"\n    },\n    {\n      \"alias\": \"dev\",\n      \"label\": \"Development\",\n      \"instance\": \"mycompany-dev\",\n      \"auth\": \"basic\",\n      \"username\": \"svc_mcp_readonly\",\n      \"password\": \"your-password-here\"\n    }\n  ]\n}\n```\n\n> 📄 Full example: [sn-instance.example.json](https://raw.githubusercontent.com/ImJaineel/SN-MCP-Server/main/sn-instance.example.json)\n\n#### Common fields\n\n| Field | Required | Description |\n|---|---|---|\n| `alias` | ✅ | Short name used in tool calls (`\"prod\"`, `\"dev-2\"`) |\n| `instance` | ✅ | Subdomain (`\"mycompany-dev\"`) or full URL (`\"https://...\"`) |\n| `auth` | optional | `\"basic\"` (default) or `\"oauth2\"` |\n| `label` | optional | Human-friendly display name |\n| `default` | optional | Use either a top-level `\"default\"` alias or per-entry `\"default\": true` to select the default instance |\n\n#### Basic Auth (`auth: \"basic\"`)\n\n| Field | Required | Description |\n|---|---|---|\n| `username` | ✅ | Service account username |\n| `password` | ✅ | Password or API token |\n\n#### OAuth 2.0 (`auth: \"oauth2\"`)\n\n| Field | Required | Description |\n|---|---|---|\n| `grant_type` | ✅ | `\"client_credentials\"`, `\"password\"`, `\"authorization_code\"`, or `\"jwt_bearer\"` |\n| `client_id` / `client_secret` | ✅ | OAuth application credentials |\n| `username` / `password` | conditional | Required for `password` grant |\n| `refresh_token` | conditional | Required for `authorization_code` grant |\n| `jwt_private_key` / `jwt_subject` | conditional | Required for `jwt_bearer` grant (PEM key string & subject user) |\n| `jwt_issuer` | optional | Optional issuer value for `jwt_bearer` |\n| `token_url` | optional | Override the default token endpoint (default: `/oauth_token.do`) |\n\nDefault selection is resolved in this order:\n1. explicit top-level `\"default\"` alias in the config object\n2. an entry with `\"default\": true`\n3. the first entry in the list\n\n---\n\n### 2. Environment variables (optional)\n\nAll 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`.\n\n> **Note:** If you are running the server from a local clone, a root-level `.env` file is loaded automatically at startup.\n\n| Variable | Description | Default |\n|---|---|---|\n| `SN_INSTANCE_CONFIG` | Path to `sn-instance.json` | Auto-resolved |\n| `SN_MCP_VERBOSE` | Set to `\"true\"` to enable debug logs | `false` |\n| `LOGS_TIMEZONE` | IANA timezone for log timestamps (`CURRENT`, `GLOBAL`, or a named zone) | `CURRENT` |\n| `SN_LOG_DIR` | Override log file directory | OS temp folder |\n| `GITHUB_TOKEN` | GitHub Personal Access Token for `sn_read_docs` (branch lookup and GitHub search) | none |\n\nCLI flags are also supported as an alternative to environment variables:\n\n- `--config <path>` → sets `SN_INSTANCE_CONFIG`\n- `--verbose` → sets `SN_MCP_VERBOSE=true`\n- `--github-token <token>` → sets `GITHUB_TOKEN`\n\n---\n\n## 🔌 MCP Client Setup\n\n### For Anyone, Everyone\n\n> **VS Code:** Press `Ctrl+Shift+P`, select **Add MCP**\n\n> **Claude Desktop:** Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows)\n\n> **Gemini Code Assist:** Create or edit `~/.gemini/mcp.json`\n\n> **Amazon Q:** Create or edit `~/.aws/amazonq/mcp.json`\n\n**Using npx (recommended):**\n\n```json\n{\n  \"mcpServers\": {\n    \"servicenow\": {\n      \"command\": \"npx\",\n      \"args\": [\"sn-mcp-server\", \"--config\", \"/absolute/path/to/sn-instance.json\"],\n    }\n  }\n}\n```\n\n**Using local clone:**\n\n```json\n{\n  \"mcpServers\": {\n    \"servicenow\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/SN-MCP-Server/src/index.js\"]\n    }\n  }\n}\n```\n\n> ⚠️ Always use **absolute paths** in MCP client configs.\n\n---\n\n## ▶️ Running locally\n\n```bash\n# Standard start (auto-detects ./sn-instance.json)\nnpm start\n\n# With explicit config path\nnode src/index.js --config /path/to/sn-instance.json\n\n# With verbose logging\nnpm run dev\nnode src/index.js --config ./sn-instance.json --verbose\n\n# Auto-restart on file changes (development)\nnpm run watch\n\n# Open MCP Inspector UI in browser (test tools interactively)\nnpm run inspect\n# The inspector launcher accepts localhost and 127.0.0.1 origins so the browser can connect reliably.\n\n# Show help\nnpx sn-mcp-server --help\n```\n\n---\n\n## 🪵 Logs\n\nEach server run creates a new timestamped log file:\n\n```\n2026-04-09T14-32-01.123Z.log\n```\n\nStored in the OS temp directory:\n\n| OS | Default log location |\n|---|---|\n| Windows | `%TEMP%\\ImJaineel_SN-MCP-Instance_logs\\` |\n| macOS | `$TMPDIR/ImJaineel_SN-MCP-Instance_logs/` |\n| Linux | `/tmp/ImJaineel_SN-MCP-Instance_logs/` |\n\nOverride with `SN_LOG_DIR` env var. Log files are cleaned up automatically by the OS on reboot.\n\nThe startup banner always prints the exact log file path:\n```\nLog file : /tmp/ImJaineel_SN-MCP-Instance_logs/2026-04-09T14-32-01.123Z.log\n```\n\n---\n\n## 🧰 Available Tools\n\nThe server exposes **16 tools at runtime** when the current environment supports them:\n\n- **14 instance tools** — require a configured `sn-instance.json`\n- **2 knowledge tools** — instance-independent tools for docs and SDK guidance\n\n### 14 instance tools\n\n| Tool | Description | Visibility |\n|---|---|---|\n| `sn_list_instances` | List all configured instances and their aliases, labels, and URLs. | Visible when `sn-instance.json` is configured and loaded. |\n| `sn_ping` | Test connectivity to a specific instance or the default instance. | Visible when `sn-instance.json` is configured and loaded. |\n| `sn_get_identity` | Query users, groups, and group membership from identity tables. | Visible when `sn-instance.json` is configured and loaded. |\n| `sn_inspect_table` | Inspect table schema or search for matching tables by name/label. | Visible when `sn-instance.json` is configured and loaded. |\n| `sn_aggregate_table` | Run aggregate queries such as count, sum, avg, min, and max. | Visible when `sn-instance.json` is configured and loaded. |\n| `sn_query_table` | Generic read from any ServiceNow table with encoded queries, fields, paging, and display values. | Visible when `sn-instance.json` is configured and loaded. |\n| `sn_get_record` | Resolve and fetch a record by sys_id, record number, task table, or CMDB CI class. | Visible when `sn-instance.json` is configured and loaded. |\n| `sn_get_attachment` | Fetch attachment metadata or file content from the Attachment API. | Visible when `sn-instance.json` is configured and loaded. |\n| `sn_get_update_sets` | List update sets or drill into the files inside a specific update set. | Visible when `sn-instance.json` is configured and loaded. |\n| `sn_code_search` | Search scripting artifacts using the native ServiceNow Code Search API. | Visible when `sn-instance.json` is configured and loaded. |\n| `sn_get_scripted_artifacts` | Fetch Script Includes, Business Rules, Client Scripts, UI Actions, Scheduled Jobs, Fix Scripts, and Scripted REST artifacts. | Visible when `sn-instance.json` is configured and loaded. |\n| `sn_legacy_workflow_search` | Search classic workflow activity variable values and resolve the owning workflow versions. | Visible when `sn-instance.json` is configured and loaded. |\n| `sn_get_legacy_workflow_artifacts` | Fetch legacy workflow artifacts from wf_* tables. | Visible when `sn-instance.json` is configured and loaded. |\n| `sn_get_workflow_studio_artifacts` | Fetch Workflow Studio and Flow Designer artifacts from sys_hub_* and related tables. | Visible when `sn-instance.json` is configured and loaded. |\n\n### 2 knowledge tools\n\n| Tool | Description | Visibility |\n|---|---|---|\n| `sn_read_docs` | Search, browse, and read ServiceNowDocs markdown by release branch. Search mode returns `file_path` and `raw_url` values for direct reads, and `get_file` accepts either a raw GitHub URL or a repo-relative path. | Always visible. |\n| `sn_sdk_explain` | Query the ServiceNow SDK for explanations of SDK skills, APIs, and concepts via `now-sdk`. | Visible only when `now-sdk` is installed and can be executed successfully. |\n\n### Runtime visibility rules\n\n- **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.\n- **`sn_read_docs`** is always registered, because it does not depend on ServiceNow instance credentials.\n- **`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`\n- Every instance tool accepts an optional `instance` parameter. If omitted, the server uses the configured default instance.\n\n---\n\n## 💡 Usage Examples\n\n### Target a specific instance\n\n```\nsn_get_scripted_artifacts  table=\"sys_script_include\"  query=\"nameLIKEMorpheus\"  instance=\"prod\"\nsn_query_table  table=\"incident\"  query=\"state=1\"  instance=\"dev\"\nsn_get_update_sets  instance=\"pdi\"\n```\n\n### Query incidents\n\n```json\n{ \"tool\": \"sn_query_table\", \"table\": \"incident\", \"query\": \"active=true\", \"limit\": 5 }\n```\n\n### Search ServiceNow Docs\n\n```json\n{ \"tool\": \"sn_read_docs\", \"mode\": \"search\", \"search\": \"Install the ServiceNow SDK in an application\", \"version\": \"australia\" }\n```\n\nUse `mode\": \"get_file\"` with the returned `file_path` or `raw_url` to read the matching doc.\n\n### Get record by number\n\n```json\n{ \"tool\": \"sn_get_record\", \"number\": \"INC0012345\" }\n```\n\n### Search legacy workflows\n\n```json\n{ \"tool\": \"sn_legacy_workflow_search\", \"query\": \"morpheus\", \"instance\": \"prod\" }\n```\n\n### Aggregate\n\n```json\n{\n  \"tool\": \"sn_aggregate_table\",\n  \"table\": \"incident\",\n  \"aggregates\": [{ \"field\": \"priority\", \"function\": \"count\" }],\n  \"group_by\": [\"priority\"]\n}\n```\n\n---\n\n## 📁 Project Structure\n\n```\nSN-MCP-Server/\n├── src/\n│   ├── cli.js            ← npx entrypoint (--config, --verbose, --github-token, --help)\n│   ├── index.js          ← server bootstrap and startup banner\n│   ├── config.js         ← config path resolution and validation\n│   ├── validator.js      ← sn-instance.json schema validation\n│   ├── constants.js      ← shared repo/example URLs\n│   ├── env-loader.js     ← .env file parser (no external deps)\n│   ├── logger.js         ← structured logger, per-run log files\n│   ├── multi-client.js   ← multi-instance routing and default-instance resolution\n│   ├── sn-client.js      ← per-instance REST client\n│   ├── handler.js        ← tool name → method router\n│   ├── tools.js          ← MCP tool definitions\n│   ├── docs-client.js    ← ServiceNowDocs search/browse/read implementation\n│   └── sdk-client.js     ← ServiceNow SDK availability probe and explain helper\n├── scripts/\n│   ├── dev.js            ← development helper\n│   └── inspect.js        ← MCP Inspector launcher with origin allowlist\n├── sn-instance.json          ← your credentials (git-ignored)\n├── sn-instance.example.json  ← template with supported auth flows\n├── .env.example              ← environment variable documentation\n├── README.md                 ← full project documentation\n└── package.json\n```\n\n---\n\n## ⚠️ Troubleshooting\n\n**Invalid credentials**\n- Verify username/password in `sn-instance.json`\n- Ensure the account has REST API access enabled in ServiceNow\n\n**Instance unreachable**\n- Check the `instance` value format — subdomain or full URL\n- Verify VPN / network connectivity\n\n**`sn-instance.json` validation error**\n- The server prints a specific error message pointing to the exact field/entry\n- See the example: [sn-instance.example.json](https://raw.githubusercontent.com/ImJaineel/SN-MCP-Server/main/sn-instance.example.json)\n\n**MCP client not detecting server**\n- Always use absolute paths in MCP client config\n- Restart the MCP client after config changes\n\n---\n\n## 🔐 Security Notes\n\n- `sn-instance.json` is in `.gitignore` — never commit it\n- Use a dedicated read-only service account per instance\n- PDI instances can use `admin` credentials safely since they're isolated\n- Do not store credentials in environment variables in shared environments\n\n<!-- ---\n\n## 🧪 Testing before npm publish\n\n```bash\n# Verify scripts\nnpm run watch    # auto-restarts on file changes\nnpm run inspect  # opens MCP Inspector in browser\n\n# Test with npm link (active development)\nnpm link\nsn-mcp-server --config ./sn-instance.json\n\n# Test exact publish artifact (pre-publish verification)\nnpm pack\nnpx ./sn-mcp-server-2.1.2.tgz --config ./sn-instance.json\n\n# Preview what files will be in the package\ntar -tzf sn-mcp-server-2.1.2.tgz\n``` -->\n\n---\n\n## 🤝 Contributing\n\nPRs welcome! Please open an issue first for larger changes.\n\n## 🐛 Report a bug\n\nIf you hit a bug, please open a GitHub issue here:\n\n- https://github.com/ImJaineel/SN-MCP-Server/issues/new\n\nInclude the following in your report so it can be fixed quickly:\n\n- what you expected to happen\n- what actually happened\n- the command or MCP client configuration you used\n- the relevant log output or error text\n- any redacted snippets from `sn-instance.json` or `.env`\n\n---\n\n## 📄 License\n\nSee [LICENSE](LICENSE) for details.\n",
  "bytes": 15468,
  "sha": "33977f6e7e5e088b4aaeef8d9efd9094cedb651aacb7e73b14803cc1d6057153",
  "repo_slug": "imjaineel/sn-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_imjaineel_sn_mcp_server_5767d8cf/readme"
}