{ "markdown": "\n\n\n

\n \"ServiceNow\n

\n\n

ServiceNow MCP Server

\n\n

\n \"PyPI\"\n \"Python\"\n \"FastMCP\"\n \"Tools\"\n \"Resources\"\n \"MCP\n \"License\"\n \"CI\"\n \"Downloads\"\n

\n\n

\n The developer data plane for ServiceNow in Claude Code — Table API, schema, aggregates and update sets,
\n on any release from Tokyo up, on PDIs, in GCC, for free. Runs alongside ServiceNow's native MCP Server.\n

\n\n---\n\n`Table API` · `CMDB` · `Update Sets` · `Aggregation` · `Resources` · `Read-only mode` · `Audit log` · `OAuth 2.1+PKCE` · `Streamable HTTP` · `Claude Code Plugin` · `4 Skills`\n\n## What This Does\n\nThis MCP server gives AI assistants the raw ServiceNow data plane: any table via the Table API, the data dictionary (with inherited fields), Stats API aggregates, CMDB classes and relationships, and update sets. 19 tools and 5 resources, with tool annotations, an optional read-only mode, table allow/deny lists, hardened encoded queries, and a JSON audit line per call.\n\nBuilt with [FastMCP 4.0](https://gofastmcp.com) — speaks both the stateless MCP 2026-07-28 protocol and the legacy handshake, negotiated per connection.\n\n## Alongside ServiceNow's native MCP Server\n\nServiceNow's **MCP Server Console** (Action Fabric) exposes Now Assist skills, Knowledge Graph, flows, scripted REST and playbooks as governed tools — and **excludes the Table API by design** (\"cannot be converted to MCP tools regardless of configuration\"). This project is the other half: the developer loop that native does not serve. ServiceNow's own CEG AI CoE guide lists `uvx mcp-server-servicenow` as its community \"Path C\".\n\n| | Native MCP Server Console | This project |\n|---|---|---|\n| **Tool sources** | Now Assist skills, Knowledge Graph, subflows/actions, scripted REST (GET/POST/PUT), playbooks, MCP Apps | Table API CRUD, Stats API aggregates, `sys_dictionary` schema, update sets, CMDB via Table API |\n| **Table API** | Excluded by design | Any table, any field |\n| **Minimum release** | Zurich P9 / Australia P2 for custom tools | Tokyo+ |\n| **Entitlement** | Now Assist / AI-Native SKU (docs: Prime for inbound); metered in assists | MIT, $0, your own compute |\n| **PDIs / GCC** | Not available | Works |\n| **Auth** | OAuth 2.0 auth-code via Machine Identity Console (JWT, no DCR) | OAuth 2.1 + PKCE proxy (DCR + CIMD), static tokens, or a service account |\n| **Governance** | AI Control Tower / AI Gateway | Self-managed: `--read-only`, table allow/deny, opt-in write confirmation, audit log, tool annotations |\n| **Transport** | Streamable HTTP only | stdio + Streamable HTTP |\n| **Resources / prompts** | Roadmap | 5 resources |\n\n**Run both.** Native tells Claude what ServiceNow *means* (skills, summaries, semantic search); this server tells Claude what ServiceNow *contains* (rows, schema, aggregates, update sets). No tool-name collisions today.\n\n## Getting Started\n\n### 1. Get a ServiceNow Instance\n\nSign up for a free [Personal Developer Instance (PDI)](https://developer.servicenow.com/) — it comes pre-loaded with demo data. Wake it from the developer portal if it's hibernating.\n\n> **Note:** Instances with ServiceNow's basic-auth restriction enforced (the default on new PDIs since mid-2026) reject REST basic auth with `401 \"Required to provide Auth information\"` unless the integration user has the **`snc_basic_auth_api_access`** role. Grant it via User Administration → Users → your user → Roles.\n\n### 2. Install\n\n```bash\n# From PyPI (recommended)\npip install mcp-server-servicenow\n\n# Or run directly with uvx (no install needed)\nuvx mcp-server-servicenow --help\n```\n\n### 3. Configure Your MCP Client\n\nCopy `.mcp.json.example` to `.mcp.json` and fill in your credentials, or use the Claude Code CLI:\n\n```bash\nclaude mcp add servicenow -- uvx mcp-server-servicenow \\\n --instance-url https://your-instance.service-now.com \\\n --auth-type basic --username admin --password your-password\n```\n\n### 4. Verify\n\nAsk Claude: \"List the 5 most recent incidents\" — if it returns data, you're connected.\n\n### From Source\n\n```bash\ngit clone https://github.com/jschuller/mcp-server-servicenow.git\ncd mcp-server-servicenow\npip install -e .\n\n# Run with stdio (Claude Desktop / Claude Code)\nmcp-server-servicenow \\\n --instance-url https://your-instance.service-now.com \\\n --auth-type basic \\\n --username admin \\\n --password your-password\n\n# Or run with HTTP (remote access / Cloud Run).\n# An HTTP listener fails closed: it needs MCP endpoint auth on top of the\n# ServiceNow credentials, otherwise the server refuses to start. Static\n# bearer tokens below; see docs/deployment.md for OAuth 2.1 + PKCE.\nmcp-server-servicenow \\\n --transport streamable-http \\\n --port 8080 \\\n --mcp-static-tokens \"$(openssl rand -hex 32)\" \\\n --instance-url https://your-instance.service-now.com \\\n --auth-type basic \\\n --username admin \\\n --password your-password\n```\n\n## Available Tools\n\n### Table API (6 tools)\n| Tool | Description |\n|------|-------------|\n| `list_records` | List records from any table with filtering, field selection, and pagination |\n| `get_record` | Get a single record by sys_id |\n| `create_record` | Create a new record in any table |\n| `update_record` | Update an existing record (optional confirmation, see below) |\n| `delete_record` | Delete a record by sys_id (optional confirmation, see below) |\n| `aggregate_records` | COUNT, AVG, MIN, MAX, SUM with GROUP BY + HAVING via Stats API |\n\n### CMDB (5 tools)\n| Tool | Description |\n|------|-------------|\n| `list_ci` | List configuration items with class and query filtering |\n| `get_ci` | Get a single CI by sys_id |\n| `create_ci` | Create a new configuration item |\n| `update_ci` | Update a configuration item (optional confirmation, see below) |\n| `get_ci_relationships` | Get parent/child relationships for a CI (paged: `limit`, `offset`) |\n\n### System (3 tools)\n| Tool | Description |\n|------|-------------|\n| `get_system_properties` | Query system properties |\n| `get_current_user` | Get authenticated user info |\n| `get_table_schema` | Table data dictionary incl. inherited fields (`hierarchy`, per-field `defined_in`) |\n\n### Update Sets (5 tools)\n| Tool | Description |\n|------|-------------|\n| `list_update_sets` | List update sets with state filtering |\n| `get_update_set` | Get update set details |\n| `create_update_set` | Create a new update set |\n| `set_current_update_set` | Set the active update set |\n| `list_update_set_changes` | List changes within an update set |\n\n## Resources\n\nMCP Resources provide read-only context that LLM clients can fetch without tool calls — reducing latency and token overhead.\n\n| Resource URI | Description |\n|-------------|-------------|\n| `servicenow://schema/{table_name}` | Field definitions (name, type, label, mandatory, reference, defined_in) for any table, parents included |\n| `servicenow://instance` | Instance URL, platform version, logged-in user, timezone |\n| `servicenow://update-set/current` | Currently active update set name, sys_id, state |\n| `servicenow://cmdb/classes` | CMDB CI class hierarchy (names, labels, parent classes) |\n| `servicenow://help/query-syntax` | Encoded query operators reference (prevents hallucinated syntax) |\n\n## Safety & governance\n\nEvery tool carries MCP annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`) so clients such as Claude Code can apply their own permission policy. On top of that, the server ships its own guardrails — all off by default except the audit log:\n\n| Flag | Env var | Effect |\n|------|---------|--------|\n| `--read-only` | `SERVICENOW_READ_ONLY=true` | Hides the 7 write tools from `tools/list` **and** refuses any non-GET request at the HTTP layer |\n| `--table-allowlist a,b*` | `SERVICENOW_TABLE_ALLOWLIST` | Only these tables (exact or glob) may be accessed — applies to `table_name`, `class_name`, fixed-table tools and the schema resource |\n| `--table-denylist sys_user*` | `SERVICENOW_TABLE_DENYLIST` | These tables may never be accessed; wins over the allowlist |\n| *(always on)* | — | Table names, sys_ids, field lists and `order_by` are validated; `javascript:` in caller queries is limited to `gs.*` date helpers (`gs.daysAgo(7)`, `gs.beginningOfToday()` …) |\n| `--allow-js-queries` | `SERVICENOW_ALLOW_JS_QUERIES=true` | Re-enable arbitrary `javascript:` in queries |\n| `--write-confirm` | `SERVICENOW_WRITE_CONFIRM=true` | Ask the user before `update_record`, `update_ci`, `delete_record` (see below) |\n| `--audit-log stderr\\|off\\|PATH` | `SERVICENOW_AUDIT_LOG` | One JSON line per tool call / resource read (default: stderr) |\n\nAn audit line (keys only — never values):\n\n```json\n{\"ts\":\"2026-08-22T19:04:11.512+00:00\",\"run_id\":\"…\",\"event\":\"tool_call\",\"name\":\"update_record\",\"user\":\"admin\",\"auth_mode\":\"service-account\",\"transport\":\"stdio\",\"table\":\"incident\",\"sys_id\":\"9d385017c611228701d22104cc95c371\",\"data_keys\":[\"state\"],\"tags\":[\"table\",\"write\"],\"outcome\":\"ok\",\"duration_ms\":212.4}\n```\n\n### Write confirmation (opt-in)\n\nWith `--write-confirm`, the three destructive tools fetch the record's current values and ask the user before writing:\n\n- **Claude Code** (stdio, handshake-era protocol) and **Cursor** render the prompt as a dialog (`elicitation/create`). *Decline* stops the write; the assistant is told not to retry.\n- **2026-07-28 clients** get the same prompt as a multi round-trip `InputRequiredResult`; the server never sends one to a client that has not declared elicitation.\n- **Claude Desktop / Cowork, claude.ai connectors and headless runs** cannot show the prompt (Desktop answers with a synthetic *cancel*). They receive a `confirmation_required` error carrying the preview; the assistant shows it and re-runs with `confirm=true`.\n\nIt is off by default because the MCP client's own permission prompt is the primary human-in-the-loop, and because automation cannot answer a dialog. Enable it where an AI Steward wants a second gate.\n\n## Architecture\n\n```mermaid\ngraph TD\n CC[\"MCP Client\"]\n subgraph SERVER[\"FastMCP 4.0\"]\n TT[\"table_tools (6)\"]\n CT[\"cmdb_tools (5)\"]\n ST[\"system_tools (3)\"]\n UT[\"update_set_tools (5)\"]\n RS[\"resources (5)\"]\n SNR[\"make_sn_request\"]\n end\n subgraph AUTH[\"Auth + HTTP\"]\n AM[\"auth_manager\"]\n AR[\"api_request\"]\n end\n SN[\"ServiceNow Instance\"]\n\n CC -->|\"stdio / Streamable HTTP\"| SERVER\n TT --> SNR\n CT --> SNR\n ST --> SNR\n UT --> SNR\n RS --> SNR\n SNR --> AR\n AM -.->|\"credentials\"| AR\n AR -->|\"REST API\"| SN\n```\n\n## Configuration\n\nAdd to your MCP client config — copy the snippet for your tool:\n\n
\nClaude Code\n\n```bash\nclaude mcp add servicenow -- uvx mcp-server-servicenow \\\n --instance-url https://your-instance.service-now.com \\\n --auth-type basic --username admin --password your-password\n```\n
\n\n
\nClaude Desktop\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json`:\n```json\n{\n \"mcpServers\": {\n \"servicenow\": {\n \"command\": \"uvx\",\n \"args\": [\"mcp-server-servicenow\"],\n \"env\": {\n \"SERVICENOW_INSTANCE_URL\": \"https://your-instance.service-now.com\",\n \"SERVICENOW_AUTH_TYPE\": \"basic\",\n \"SERVICENOW_USERNAME\": \"admin\",\n \"SERVICENOW_PASSWORD\": \"your-password\"\n }\n }\n }\n}\n```\n
\n\n
\nCursor / VS Code\n\nAdd to `.cursor/mcp.json` or `.vscode/mcp.json`:\n```json\n{\n \"mcpServers\": {\n \"servicenow\": {\n \"command\": \"uvx\",\n \"args\": [\"mcp-server-servicenow\"],\n \"env\": {\n \"SERVICENOW_INSTANCE_URL\": \"https://your-instance.service-now.com\",\n \"SERVICENOW_AUTH_TYPE\": \"basic\",\n \"SERVICENOW_USERNAME\": \"admin\",\n \"SERVICENOW_PASSWORD\": \"your-password\"\n }\n }\n }\n}\n```\n
\n\nSee [Configuration Guide](docs/configuration.md) for OAuth, multi-instance, and the full environment variable reference.\n\n## Deployment\n\nSee [Deployment Guide](docs/deployment.md) — Docker, Cloud Run, HTTP transport verification, and the security model.\n\n## Troubleshooting\n\nSee [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for common issues (hibernating instances, 401 errors, OAuth).\n\n## Development\n\n```bash\n# Install with dev dependencies\npip install -e \".[dev]\"\n\n# Run unit tests\npython -m pytest tests/ -v --ignore=tests/integration\n\n# Run integration tests (requires PDI credentials)\n# Option 1: Create .env.test (gitignored, auto-loaded)\ncp .env.example .env.test # then fill in your credentials\npython -m pytest tests/integration/ -v\n\n# Option 2: Inline env vars\nSERVICENOW_INSTANCE_URL=https://your-pdi.service-now.com \\\nSERVICENOW_USERNAME=admin SERVICENOW_PASSWORD=your-password \\\npython -m pytest tests/integration/ -v\n\n# Lint\nruff check src/ tests/\n```\n\n## Skills (Claude Code)\n\nThis project ships 4 Claude Code skills in `skills/` (installed via the plugin, not the PyPI package) — guided workflows that chain MCP tools for common ServiceNow tasks. Skills auto-trigger from natural conversation or can be invoked directly.\n\n| Skill | What It Does | Try Saying |\n|-------|-------------|------------|\n| **servicenow-cmdb** | CI classes, dependencies, CMDB health, data quality, CSDM compliance | \"show me CMDB health\" / \"what depends on this server\" |\n| **exploring-tables** | Schema discovery, field types, data profiling, table comparison | \"what fields does incident have\" / \"find tables matching cmdb\" |\n| **reviewing-update-sets** | Update set review, risk flagging, conflict detection, pre-promotion checks | \"review my update sets\" / \"is this safe to promote\" |\n| **triaging-incidents** | Incident triage, priority assessment, CI correlation, bulk analysis | \"what's on fire\" / \"open P1 incidents\" |\n\nThe **update set reviewer** is a unique differentiator — no other open-source ServiceNow MCP server provides guided update set review workflows with risk categorization and pre-promotion checklists.\n\n## Claude Code Plugin\n\nInstall as a Claude Code plugin for zero-config setup — the MCP server, skills, slash commands, and admin agent are bundled together.\n\n### Prerequisites\n\nSet these environment variables (or add them to your shell profile):\n\n```bash\nexport SERVICENOW_INSTANCE_URL=\"https://your-instance.service-now.com\"\nexport SERVICENOW_AUTH_TYPE=\"basic\" # or \"oauth\"\nexport SERVICENOW_USERNAME=\"admin\"\nexport SERVICENOW_PASSWORD=\"your-password\"\n# For OAuth only:\nexport SERVICENOW_CLIENT_ID=\"your-client-id\"\nexport SERVICENOW_CLIENT_SECRET=\"your-client-secret\"\n```\n\n### Install from Git\n\n```bash\nclaude plugin marketplace add jschuller/mcp-server-servicenow\nclaude plugin install servicenow@mcp-server-servicenow\n```\n\n### Install Locally (development)\n\n```bash\nclaude --plugin-dir /path/to/mcp-server-servicenow\n```\n\n### Slash Commands\n\n| Command | Description |\n|---------|-------------|\n| `/servicenow:triage` | Triage incidents — list, investigate, assess priority, analyze trends |\n| `/servicenow:cmdb` | Explore CMDB — CI hierarchy, dependencies, health, CSDM taxonomy |\n| `/servicenow:review-update-set` | Review update sets — deep review, compare, pre-promotion checks |\n| `/servicenow:explore-table` | Explore tables — schema, fields, data profiling, table search |\n\n### Agent\n\nThe `servicenow-admin` agent handles complex multi-step tasks autonomously (CMDB audits, incident trend reports, batch update set reviews). Claude can spawn it as a background worker for long-running analysis.\n\n> **Note:** The plugin auto-configures the MCP server — no manual `.mcp.json` setup required.\n\n## Roadmap\n\n- **Phase 1** ✅ Foundation — 18 tools, OAuth retry, structured error handling\n- **Phase 2** ✅ Remote access — FastMCP 3.0, Streamable HTTP, Cloud Run deployment\n- **Phase 3** ✅ Security — OAuth 2.1 + PKCE proxy, per-user SN auth, matches native Zurich model\n- **Phase 4** ✅ Skills & workflows — 4 Claude Code skills (CMDB, table explorer, update set reviewer, incident triage)\n- **Phase 4.5** ✅ Plugin packaging — Claude Code plugin with slash commands, admin agent, zero-config install\n- **Phase 5** ✅ Distribution — PyPI package, [MCP Registry](https://registry.modelcontextprotocol.io), automated publish workflows\n- **Sprint 2** ✅ FastMCP 3.1.1 — MultiAuth, token caching, connection pooling, response limiting, tool tags\n- **Sprint 3** ✅ Resources + Aggregation — 5 MCP resources, `aggregate_records` Stats API tool\n- **v0.6.0** ✅ FastMCP 4.0 — MCP 2026-07-28 stateless protocol support, fail-closed HTTP hardening, community fixes\n- **v0.6.1** ✅ OAuth ROPC timeout + refresh-token grant, mypy in CI, dependency refresh\n- **v0.7.0** ✅ Safety & governance — tool annotations, read-only mode, table allow/deny lists, opt-in destructive-call confirmation, JSON audit log, schema inheritance\n- **Next** — \"Run alongside native\" guide, MCP prompts from the skills, per-token scopes over HTTP, developer-plane tools (system logs, health checks)\n\n## Related Projects\n\n- **[sn-app-template](https://github.com/jschuller/sn-app-template)** — ServiceNow scoped app template for Claude Code + now-sdk. Pairs with this MCP server for AI-assisted development.\n\n## License\n\n[MIT](LICENSE)\n", "bytes": 18669, "sha": "ec686c256abda89945a6525d12ee5dc14e101de29d15e9921bd60486461e7288", "repo_slug": "jschuller/mcp-server-servicenow", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_jschuller_mcp_server_serviceno_000e9d6b/readme" }