{"id":48104119,"url":"https://github.com/jschuller/mcp-server-servicenow","last_synced_at":"2026-04-04T15:50:07.923Z","repository":{"id":340069111,"uuid":"1152294473","full_name":"jschuller/mcp-server-servicenow","owner":"jschuller","description":"MCP server for ServiceNow — 18 tools for incidents, CMDB, update sets. OAuth 2.1+PKCE, Claude Code skills, FastMCP 3.0. Works on any SN version (Tokyo+), no entitlements needed.","archived":false,"fork":false,"pushed_at":"2026-03-22T18:26:26.000Z","size":973,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-23T08:29:02.621Z","etag":null,"topics":["ai-tools","claude-code","cmdb","fastmcp","itsm","mcp","mcp-server","model-context-protocol","oauth","servicenow"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jschuller.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-07T17:01:55.000Z","updated_at":"2026-03-22T18:26:28.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jschuller/mcp-server-servicenow","commit_stats":null,"previous_names":["jschuller/mcp-server-servicenow"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/jschuller/mcp-server-servicenow","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jschuller%2Fmcp-server-servicenow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jschuller%2Fmcp-server-servicenow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jschuller%2Fmcp-server-servicenow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jschuller%2Fmcp-server-servicenow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jschuller","download_url":"https://codeload.github.com/jschuller/mcp-server-servicenow/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jschuller%2Fmcp-server-servicenow/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31404050,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T10:20:44.708Z","status":"ssl_error","status_checked_at":"2026-04-04T10:20:06.846Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-tools","claude-code","cmdb","fastmcp","itsm","mcp","mcp-server","model-context-protocol","oauth","servicenow"],"created_at":"2026-04-04T15:50:07.029Z","updated_at":"2026-04-04T15:50:07.856Z","avatar_url":"https://github.com/jschuller.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- mcp-server: servicenow | tools: 19 | resources: 5 | transport: stdio,streamable-http | auth: basic,oauth,api_key | framework: fastmcp-3.1 --\u003e\n\u003c!-- mcp-name: io.github.jschuller/mcp-server-servicenow --\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/jschuller/mcp-server-servicenow/main/docs/hero.png\" alt=\"ServiceNow MCP Server\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eServiceNow MCP Server\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://pypi.org/project/mcp-server-servicenow/\"\u003e\u003cimg src=\"https://img.shields.io/pypi/v/mcp-server-servicenow?color=005E4D\u0026label=PyPI\" alt=\"PyPI\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.python.org/\"\u003e\u003cimg src=\"https://img.shields.io/badge/Python-3.11+-005E4D\" alt=\"Python\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://gofastmcp.com\"\u003e\u003cimg src=\"https://img.shields.io/badge/FastMCP-3.1-00A893\" alt=\"FastMCP\"\u003e\u003c/a\u003e\n  \u003ca href=\"#available-tools\"\u003e\u003cimg src=\"https://img.shields.io/badge/Tools-19-00A893\" alt=\"Tools\"\u003e\u003c/a\u003e\n  \u003ca href=\"#resources\"\u003e\u003cimg src=\"https://img.shields.io/badge/Resources-5-00A893\" alt=\"Resources\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://modelcontextprotocol.io\"\u003e\u003cimg src=\"https://img.shields.io/badge/MCP-2025--11--25-5436DA\" alt=\"MCP Protocol\"\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-MIT-blue\" alt=\"License\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/jschuller/mcp-server-servicenow/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/jschuller/mcp-server-servicenow/actions/workflows/ci.yml/badge.svg\" alt=\"CI\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://pypi.org/project/mcp-server-servicenow/\"\u003e\u003cimg src=\"https://img.shields.io/pypi/dm/mcp-server-servicenow?color=005E4D\u0026label=downloads\" alt=\"Downloads\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  Connect Claude AI to ServiceNow. 19 tools + 5 resources for incidents, CMDB, update sets, and more —\u003cbr\u003e\n  accessible from Claude Desktop, Claude Code, or any MCP client over stdio or Streamable HTTP.\n\u003c/p\u003e\n\n---\n\n`Table API` · `CMDB` · `Update Sets` · `Aggregation` · `Resources` · `OAuth 2.1+PKCE` · `Streamable HTTP` · `Claude Code Plugin` · `4 Skills`\n\n## What This Does\n\nThis MCP server lets AI assistants interact directly with a ServiceNow instance. Instead of copy-pasting between ServiceNow and your AI tool, Claude can query incidents, create records, explore CMDB relationships, and manage update sets through natural conversation.\n\nBuilt with [FastMCP 3.1](https://gofastmcp.com) for decorator-based tool definitions, MCP resources, and dual transport support.\n\n## Native vs Community\n\nServiceNow shipped a native MCP Server in Zurich (2025). Here's when to use each:\n\n| | Native (Zurich+) | This project |\n|---|---|---|\n| **SN version** | Zurich+ only | Any version (Tokyo+) |\n| **Entitlement** | Requires Now Assist SKU | None (MIT, free) |\n| **Auth model** | OAuth 2.1 + PKCE via AI Control Tower | OAuth 2.1 + PKCE via FastMCP proxy |\n| **Governance** | AI Control Tower policies | Self-managed |\n| **Table access** | Governed by CT config | Full table API access |\n| **AI models** | Now Assist models + approved | Any MCP client (Claude, GPT, etc.) |\n| **Custom tools** | Requires SN development | Python — add tools in minutes |\n\n**Use native** if you're on Zurich+ with Now Assist and need AI Control Tower governance.\n**Use this** if you're on an older version, don't have the entitlement, need custom table access, or want to use any AI model.\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### 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)\nmcp-server-servicenow \\\n  --transport streamable-http \\\n  --port 8080 \\\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 |\n| `delete_record` | Delete a record by sys_id |\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 |\n| `get_ci_relationships` | Get parent/child relationships for a CI |\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` | Get table data dictionary (field definitions) |\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) for any table |\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## Architecture\n\n```mermaid\ngraph TD\n    CC[\"MCP Client\"]\n    subgraph SERVER[\"FastMCP 3.1\"]\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 --\u003e|\"stdio / Streamable HTTP\"| SERVER\n    TT --\u003e SNR\n    CT --\u003e SNR\n    ST --\u003e SNR\n    UT --\u003e SNR\n    RS --\u003e SNR\n    SNR --\u003e AR\n    AM -.-\u003e|\"credentials\"| AR\n    AR --\u003e|\"REST API\"| SN\n```\n\n## Configuration\n\nAdd to your MCP client config — copy the snippet for your tool:\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eClaude Code\u003c/strong\u003e\u003c/summary\u003e\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\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eClaude Desktop\u003c/strong\u003e\u003c/summary\u003e\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\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eCursor / VS Code\u003c/strong\u003e\u003c/summary\u003e\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\u003c/details\u003e\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 `.claude/skills/` — 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 add --from https://github.com/jschuller/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\u003e **Note:** The plugin auto-configures the MCP server — no manual `.mcp.json` setup required.\n\n## Roadmap\n\n- **Phase 1** \u0026#x2705; Foundation — 18 tools, OAuth retry, structured error handling\n- **Phase 2** \u0026#x2705; Remote access — FastMCP 3.0, Streamable HTTP, Cloud Run deployment\n- **Phase 3** \u0026#x2705; Security — OAuth 2.1 + PKCE proxy, per-user SN auth, matches native Zurich model\n- **Phase 4** \u0026#x2705; Skills \u0026 workflows — 4 Claude Code skills (CMDB, table explorer, update set reviewer, incident triage)\n- **Phase 4.5** \u0026#x2705; Plugin packaging — Claude Code plugin with slash commands, admin agent, zero-config install\n- **Phase 5** \u0026#x2705; Distribution — PyPI package, [MCP Registry](https://registry.modelcontextprotocol.io), automated publish workflows\n- **Sprint 2** \u0026#x2705; FastMCP 3.1.1 — MultiAuth, token caching, connection pooling, response limiting, tool tags\n- **Sprint 3** \u0026#x2705; Resources + Aggregation — 5 MCP resources, `aggregate_records` Stats API tool\n- **Next** — Enhancement backlog under active consideration (background scripts, error enrichment, 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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjschuller%2Fmcp-server-servicenow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjschuller%2Fmcp-server-servicenow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjschuller%2Fmcp-server-servicenow/lists"}