{
  "markdown": "<p align=\"center\">\n  <img src=\"https://happy-tech.biz/images/logo.svg\" alt=\"Happy MCP Server\" width=\"120\" height=\"120\">\n</p>\n\n<h1 align=\"center\">Happy MCP Server</h1>\n\n<p align=\"center\">\n  <strong>Model Context Protocol Server for the ServiceNow&reg; Platform</strong></p>\n\n<p align=\"center\">\n  A metadata-driven MCP server that auto-generates 480+ tools across 160+ tables, with multi-instance support, natural language search, and local script development.\n</p>\n\n<p align=\"center\">\n  <a href=\"https://www.npmjs.com/package/happy-platform-mcp\"><img src=\"https://img.shields.io/npm/v/happy-platform-mcp.svg?style=flat-square\" alt=\"npm version\"></a>\n  <a href=\"https://opensource.org/licenses/Apache-2.0\"><img src=\"https://img.shields.io/badge/License-Apache%202.0-blue.svg?style=flat-square\" alt=\"License: Apache 2.0\"></a>\n  <a href=\"https://nodejs.org\"><img src=\"https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg?style=flat-square\" alt=\"Node.js Version\"></a>\n</p>\n\n<p align=\"center\">\n  <a href=\"https://happy-tech.biz\">Website</a> |\n  <a href=\"https://github.com/Happy-Technologies-LLC/happy-platform-mcp\">GitHub</a> |\n  <a href=\"https://www.npmjs.com/package/happy-platform-mcp\">npm</a> |\n  <a href=\"#tool-overview\">Tools</a> |\n  <a href=\"CONTRIBUTING.md\">Contributing</a> |\n  <a href=\"#support\">Support</a>\n</p>\n\n---\n\n> **Migrating from `servicenow-mcp-server`?** The npm package has been renamed to `happy-platform-mcp` and the Docker image to `nczitzer/happy-platform-mcp`. The old names are deprecated but will continue to work temporarily. Update your dependencies:\n> ```bash\n> # npm\n> npm uninstall servicenow-mcp-server && npm install happy-platform-mcp\n>\n> # Docker\n> docker pull nczitzer/happy-platform-mcp:latest\n> ```\n\n## Support\n\nIf you find this project useful, consider supporting its development. Contributions support Happy Technologies LLC.\n\n- [GitHub Sponsors](https://github.com/sponsors/Happy-Technologies-LLC)\n- [Buy Me a Coffee](https://buymeacoffee.com/nickzitzer)\n## Features\n\n- **Multi-Instance Support** — Connect to multiple ServiceNow&reg; instances simultaneously with per-request routing\n- **OAuth 2.0 & Basic Auth** — Per-instance Client Credentials, Resource Owner Password Credentials, and per-user Authorization Code with PKCE\n- **Intelligent Schema Discovery** — Automatically discovers table structures and relationships at runtime\n- **160+ Tables** — Complete coverage including ITSM, CMDB, Service Catalog, Platform Development, and Flow Designer\n- **55 MCP Tools** — Generic CRUD operations that work on any table, plus specialized convenience tools\n- **Batch Operations** — 43+ parallel operations tested successfully\n- **Local Script Development** — Sync scripts with Git, watch mode for continuous development\n- **Natural Language Search** — Query using plain English instead of encoded queries\n- **MCP Resources** — 8 read-only resource URIs for quick lookups and documentation\n- **Background Script Execution** — Automated server-side script execution via `sys_trigger`\n- **Service Catalog AI-Submission** — Browse, inspect, and submit Service Catalog forms programmatically\n- **ServiceNow Docs Search** — Optional GitHub-backed docs retrieval and local SQLite FTS search over official ServiceNowDocs markdown\n\n## Quick Start\n\n### Prerequisites\n\n- Node.js 20+\n- One or more ServiceNow&reg; instances with REST API access\n- Valid credentials for each instance\n\n### Install from npm\n\n```bash\nnpx happy-platform-mcp\n```\n\nOr install globally:\n\n```bash\nnpm install -g happy-platform-mcp\n```\n\n### Install from Source\n\n```bash\ngit clone https://github.com/Happy-Technologies-LLC/happy-platform-mcp.git\ncd happy-platform-mcp\nnpm install\n# Source checkout: use node src/cli.js <command>, or npm link first.\nnode src/cli.js instance list\n```\n\n### Start the stdio server\n\nAfter a global install, `happy-platform-mcp` with no arguments starts the\nstdio MCP server:\n\n```bash\nnpm install -g happy-platform-mcp\nSERVICENOW_INSTANCE=dev happy-platform-mcp\n```\n\nAn MCP host can use the global command:\n\n```json\n{\n  \"mcpServers\": {\n    \"happy-mcp-server\": {\n      \"command\": \"happy-platform-mcp\",\n      \"env\": { \"SERVICENOW_INSTANCE\": \"dev\" }\n    }\n  }\n}\n```\n\nOr use `npx` with `command: \"npx\"` and `args: [\"-y\", \"happy-platform-mcp\"]`.\nFrom a source checkout, use `node src/stdio-server.js`; source CLI commands\nuse `node src/cli.js instance ...`.\n\n### Configure Instances\n\n**Recommended: register metadata with the local CLI**\n\nThe CLI inherits the environment of the process that launches it. The CLI\ndoes not auto-load `.env`; `.env` loading applies to the server/stdio\nprocess only. For CLI use, export `HAPPY_CONFIG_PATH` in the shell (or set it\nin the MCP host environment when the host launches the CLI). The actual\ndefault registry path on every OS is\n`<homedir>/.config/happy-platform-mcp/instances.json`, using native path\nseparators for that OS.\n\nCredentials are prompted locally, masked, and stored in the operating system\nkeychain. A new CLI-written version 1 registry contains instance metadata and\ncanonical `credentialRef` values only; it does not contain plaintext\ncredentials. Legacy plaintext registry files are read-only compatibility\ninputs, and the singular `SERVICENOW_*` environment fallback is retained only\nfor backward compatibility.\n\n```bash\nhappy-platform-mcp instance add\nhappy-platform-mcp instance list\nhappy-platform-mcp instance test dev\nhappy-platform-mcp instance update dev\nhappy-platform-mcp instance remove dev\nhappy-platform-mcp instance migrate\n```\n\n`instance add` prompts once for the credentials required by the selected auth\nmode and stores them before registering metadata. `instance credential set` is\nonly for rotating an existing credential or completing a metadata-only MCP\nregistration. `instance update` changes metadata only. Authentication changes\nrequire `instance remove` followed by `instance add`. Secret prompts never put\nvalues in command arguments, logs, or MCP messages. These\nprompts require an interactive local TTY. In non-TTY automation, use a\npre-provisioned OS keychain entry and run metadata-only commands; the CLI will\nnot read secrets from stdin or silently fall back to plaintext.\n\nTo select a different metadata registry for the CLI, export\n`HAPPY_CONFIG_PATH` before invoking it:\n\n```bash\nexport HAPPY_CONFIG_PATH=\"$HOME/.config/happy-platform-mcp/instances.json\"\nhappy-platform-mcp instance list\n```\n\nFor an MCP server/stdio host, set the same variable in the host environment:\n\n```json\n{\n  \"env\": {\n    \"HAPPY_CONFIG_PATH\": \"~/.config/happy-platform-mcp/instances.json\"\n  }\n}\n```\n\n`HAPPY_CONFIG_PATH` supports `~` and relative paths. For migration, automatic\npackage-legacy -> user-registry migration is available only when the resolver\nselects the package-relative `config/servicenow-instances.json` as\n`readPath` and the distinct default user registry as `writePath`.\n`HAPPY_CONFIG_PATH` normally selects both `readPath` and `writePath` and must\npoint to a metadata-only version 1 registry. If it points to a plaintext\nsource (the same file), the CLI refuses before any keychain write; source\nbytes and keychain entries remain unchanged. Choose a distinct\n`HAPPY_CONFIG_PATH` target, or unset it for the automatic workflow. Never\ncopy secrets into command arguments. For a non-package legacy source, use a\ncontrolled distinct source/target workflow or manually use `instance add` and\nthe masked `instance credential set` prompt.\n\n`SN-Register-Instance` normally applies a live registry reload and does not\nrequire a restart. Restart the MCP server only for docs-only mode or when the\nreload fails.\n\n**Legacy compatibility:** `config/servicenow-instances.json` is a read-only\nlegacy migration input. The singular `SERVICENOW_*` environment variables are\nthe backward-compatible single-instance fallback only when no registry is\navailable. The package-relative file is not the CLI's writable location.\n\n**Option B: Single Instance (legacy environment fallback)**\n\n```bash\ncp .env.example .env\n# Server/stdio only: set legacy SERVICENOW_* variables in .env.\n```\n\n### Start the Server\n\n```bash\n# HTTP/SSE transport\nnpm run dev\n\n# Stdio transport (for Claude Desktop)\nnpm run stdio\n```\n\nHTTP/SSE listens on `127.0.0.1` by default. To expose it through a reverse proxy or network interface, set both `HAPPY_MCP_BIND_HOST` and a high-entropy `HAPPY_MCP_API_TOKEN`; clients must send `Authorization: Bearer <token>`.\n\n### Verify\n\n```bash\ncurl http://localhost:3000/health\ncurl http://localhost:3000/instances\n\n# Required when HAPPY_MCP_API_TOKEN is set\ncurl -H \"Authorization: Bearer $HAPPY_MCP_API_TOKEN\" http://localhost:3000/health\n```\n\n## Multi-Instance Routing\n\nEvery live ServiceNow operation accepts an optional `instance` parameter, except `SN-Set-Instance`, `SN-Get-Current-Instance`, and `SN-Docs-*`. Omitting it uses the current session client's implicit target. Explicit routing is required when overlapping work may target different instances or race with `SN-Set-Instance`; concurrent calls against one stable implicit target do not require it. Explicit calls are cached by instance name, so calls to the same named instance share that client.\n\nAt stdio startup, `SERVICENOW_INSTANCE` selects a named JSON entry when set; otherwise startup uses the entry marked `\"default\": true`, or the first configured entry if none is marked. HTTP sessions use the configured default or first entry. If the JSON file is missing, ServiceNow environment credentials can provide the single fallback instance. The `\"default\": true` flag is startup configuration. `SN-Set-Instance` changes only the current session client in memory; it never edits configuration, and a new MCP session or server starts from startup selection again.\n\n```javascript\n// Uses this session client's current implicit target\nawait client.callTool({\n  name: 'SN-Query-Table',\n  arguments: { table_name: 'incident', limit: 10 }\n});\n\n// Safely query dev and prod concurrently\nawait Promise.all([\n  client.callTool({\n    name: 'SN-Query-Table',\n    arguments: { table_name: 'incident', instance: 'dev', limit: 10 }\n  }),\n  client.callTool({\n    name: 'SN-Query-Table',\n    arguments: { table_name: 'incident', instance: 'prod', limit: 10 }\n  })\n]);\n```\n\n## Tool Overview\n\n| Category | Tools | Description |\n|----------|-------|-------------|\n| **Generic CRUD** | 7 | Query, Create, Get, Update on any table |\n| **Specialized ITSM** | 8 | Incident, Change, Problem convenience wrappers |\n| **Convenience** | 10 | Add-Comment, Add-Work-Notes, Assign, Resolve, Close |\n| **Natural Language** | 1 | Query using plain English |\n| **Update Sets** | 6 | Set, list, move, clone, inspect update sets |\n| **Scripts** | 2 | Execute background scripts, create fix scripts |\n| **Script Sync** | 3 | Sync scripts with local files, watch mode |\n| **Workflows** | 4 | Create workflows, activities, transitions |\n| **Batch** | 2 | Batch create/update across tables |\n| **Schema** | 3 | Table schemas, field info, relationships |\n| **Service Catalog** | 4 | Browse, inspect, and submit catalog forms |\n| **ServiceNow Docs** | 5 | Discover, sync, search, and retrieve official ServiceNowDocs markdown |\n| **Resources** | 8 | Read-only URIs for table lists, field info |\n\n### Examples\n\nThe following transport-neutral examples show an MCP tool name followed by its arguments:\n\n```text\nSN-Query-Table\n{ \"table_name\": \"incident\", \"query\": \"active=true^priority=1\", \"limit\": 10 }\n\nSN-Create-Incident\n{ \"short_description\": \"Email service down\", \"urgency\": 1 }\n\nSN-NL-Search\n{ \"table_name\": \"incident\", \"query\": \"high priority incidents assigned to me\" }\n\nSN-Execute-Background-Script\n{ \"script\": \"gs.info('Hello');\" }\n\nSN-Set-Update-Set\n{ \"update_set_sys_id\": \"abc123...\" }\n\nSN-Batch-Update\n{ \"updates\": [{ \"table\": \"incident\", \"sys_id\": \"id1\", \"data\": { \"state\": 2 } }] }\n\nSN-Catalog-Search-Items\n{ \"keyword\": \"VPN access\" }\nSN-Catalog-Get-Item\n{ \"sys_id\": \"<catalog_item_sys_id>\" }\nSN-Catalog-Submit\n{ \"sys_id\": \"<catalog_item_sys_id>\", \"variables\": { \"requested_for\": \"jsmith\", \"justification\": \"Project X\" } }\n\nSN-Docs-Families\n{}\nSN-Docs-Sync\n{ \"family\": \"australia\" }\nSN-Docs-Search\n{ \"query\": \"create a Flow Designer action\", \"family\": \"australia\" }\n```\n\n### Local Script Development\n\nDevelop scripts locally with version control and automatic sync:\n\n```text\nSN-Sync-Script-To-Local\n{\n  \"script_sys_id\": \"abc123...\",\n  \"local_path\": \"/scripts/business_rules/validate_incident.js\"\n}\n\nSN-Watch-Script\n{\n  \"local_path\": \"/scripts/business_rules/validate_incident.js\",\n  \"script_sys_id\": \"abc123...\"\n}\n```\n\n### Natural Language Search\n\n```text\nSN-NL-Search\n{\n  \"table_name\": \"incident\",\n  \"query\": \"active high priority incidents that are unassigned\"\n}\n```\n\nSupports 15+ patterns including field comparisons, text searches, date ranges, logical operators, and ordering.\n\n### ServiceNow Docs Search\n\nHappy MCP can retrieve official ServiceNowDocs markdown directly from GitHub and optionally localize a docs family into a SQLite FTS5 index for fast local search. Local indexing is disabled by default; enable it with `docs.localIndexEnabled=true` in the version 1 registry or `HAPPY_DOCS_ENABLE_LOCAL_INDEX=true`.\n\n```text\nSN-Register-Instance\n{ \"name\": \"dev\", \"url\": \"https://your-instance.service-now.com\", \"username\": \"your-username\" }\n\nSN-Docs-Families\n{}\nSN-Docs-Status\n{}\nSN-Docs-Sync\n{ \"family\": \"australia\" }\nSN-Docs-Search\n{ \"query\": \"update set best practices\", \"family\": \"australia\", \"limit\": 5 }\nSN-Docs-Get\n{ \"family\": \"australia\", \"path\": \"platform/example.md\" }\n```\n\n`SN-Register-Instance` accepts metadata only. It never accepts passwords,\nclient secrets, or other secret fields. If a required local credential is\nmissing, its response gives the exact `happy-platform-mcp instance credential\nset ...` command to run locally. Registration persists metadata, but a\ndocs-only server must be restarted before live ServiceNow tools are enabled.\n\nSQLite local indexing is optional and disabled by default. Vector search is also optional; enable local indexing, set `HAPPY_DOCS_ENABLE_VECTOR=true`, and use `HAPPY_DOCS_EMBEDDING_PROVIDER=local` to build a sqlite-vec index with deterministic local embeddings. See [ServiceNow Docs Search](docs/SERVICENOW_DOCS_SEARCH.md).\n\nFor docs-only deployments without ServiceNow credentials, set `HAPPY_MCP_DOCS_ONLY=true`. If no config file or ServiceNow environment credentials are present, the stdio server falls back to docs-only mode automatically.\n\n### Runtime instance selection\n\nRegistration and runtime selection are separate:\n\n- Registration persists an available named instance in the registry.\n- `SERVICENOW_INSTANCE` chooses the stdio startup default only.\n- `SN-Set-Instance` changes the sequential session's shared implicit target in memory; it does not edit the registry.\n- The optional per-call `instance` argument selects an isolated request target, so concurrent calls can route to different instances without racing the sequential target.\n\n## Claude Desktop Integration\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\nFor a global install, no arguments starts stdio:\n\n```json\n{\n  \"mcpServers\": {\n    \"happy-mcp-server\": {\n      \"command\": \"happy-platform-mcp\",\n      \"env\": { \"SERVICENOW_INSTANCE\": \"dev\" }\n    }\n  }\n}\n```\n\nFor an ephemeral install, use `command: \"npx\"` with\n`args: [\"-y\", \"happy-platform-mcp\"]`:\n\n```json\n{\n  \"mcpServers\": {\n    \"happy-mcp-server\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"happy-platform-mcp\"],\n      \"env\": {\n        \"HAPPY_CONFIG_PATH\": \"~/.config/happy-platform-mcp/instances.json\"\n      }\n    }\n  }\n}\n```\n\nThe registry setting points to metadata; credentials remain in the local OS\nkeychain. `HAPPY_CONFIG_PATH` is optional with the default user path and must\nbe set before the server starts. For source installs, use\n`node src/stdio-server.js` in the host config and `node src/cli.js instance\n<command>` for CLI operations. Restart Claude Desktop after editing its config.\n\n## Authentication\n\nHappy MCP Server supports three credential flows per instance. Interactive\n`instance add` captures each required secret once, stores it in the OS\nkeychain, and registers the metadata. Use `instance credential set` later only\nto rotate an existing credential or complete metadata-only MCP registration.\nNever place secrets in JSON or command arguments.\n\n### Global CLI: dev basic authentication\n\n```bash\nhappy-platform-mcp instance add\n# Select Basic authentication; set the name to dev, enter URL and username,\n# then enter the masked password when prompted. The command stores it once.\nhappy-platform-mcp instance test dev\n```\n\n### Global CLI: prod OAuth client credentials\n\n```bash\nhappy-platform-mcp instance add\n# Select OAuth -> Client credentials; set the name to prod, enter URL and\n# client ID, then enter the masked client secret. The command stores it once.\nhappy-platform-mcp instance test prod\n```\n\n### OAuth password grant\n\n```bash\nhappy-platform-mcp instance add\n# Select OAuth -> Password grant; enter URL, client ID, and username, then\n# enter both masked prompts. The command stores both credentials once.\nhappy-platform-mcp instance test password-prod\n```\n\nPassword grant `credentialRef` must be an object containing both canonical\nreferences:\n\n```json\n\"credentialRef\": {\n  \"password\": \"keychain:instance/password-prod/password\",\n  \"clientSecret\": \"keychain:instance/password-prod/client-secret\"\n}\n```\n\n### Public authorization code with PKCE\n\n```bash\nhappy-platform-mcp instance add\n# Select OAuth -> Authorization code and enter URL, client ID,\n# authorize URL, token URL, redirect port, and callback path.\nhappy-platform-mcp instance test public-dev\n```\n\nPublic authorization-code metadata requires no `credentialRef` or client\nsecret. The first test/API call opens the browser flow and stores its refresh\ntoken in the OS keychain.\n## Architecture\n\n```\nsrc/\n├── server.js                     # Express HTTP server (SSE transport)\n├── stdio-server.js               # Stdio transport (Claude Desktop)\n├── mcp-server-consolidated.js    # MCP tool registration & routing\n├── servicenow-client.js          # REST API client\n└── config-manager.js             # Multi-instance configuration\n\nconfig/\n└── servicenow-instances.json     # Instance configuration\n\ndocs/\n├── API_REFERENCE.md              # Complete tool reference\n├── SETUP_GUIDE.md                # Detailed setup instructions\n└── research/                     # Technical research & discoveries\n```\n\n## Testing\n\n```bash\n# Run tests\nnpm test\n\n# Watch mode\nnpm run test:watch\n\n# Coverage\nnpm run test:coverage\n\n# MCP Inspector\nnpm run inspector\n```\n\n## Troubleshooting\n\n### Connection Issues\n\n```bash\n# Test configured credentials without exposing them in shell history.\nhappy-platform-mcp instance test <instance-name>\n\n# Check server health\ncurl http://localhost:3000/health\n```\n\n### Common Problems\n\n- **Multi-instance not working:** Verify the version 1 registry is valid JSON and has one `\"default\": true` instance when a startup default is needed. Normal live registration reloads without a restart; restart only for docs-only mode or a reload failure.\n- **Tools not appearing:** Check MCP Inspector connection and server logs.\n- **Auth failures:** Run `happy-platform-mcp instance test <instance-name>` and verify the local keychain credential reference and required ServiceNow roles.\n- **SSE disconnects in Docker:** Enable keepalive (default 15s). See `docs/SSE_DOCKER_SETUP.md`.\n\n### Debug Mode\n\n```bash\nDEBUG=true npm run dev\n```\n\n## Known Limitations\n\n- Flow Designer logic blocks cannot be created via REST API (use the UI)\n- Flow compilation/validation must be done in the UI\n- UI Policy Actions linking requires a background script workaround\n\nSee the API reference and tool-specific guides under `docs/` for details.\n\n## Acknowledgments\n\nThis project was inspired by the [Echelon AI Labs ServiceNow MCP Server](https://github.com/echelon-ai-labs/servicenow-mcp). We are grateful for their pioneering work in bringing MCP capabilities to the ServiceNow&reg; platform.\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. All contributors must sign a CLA.\n\n## Security\n\nTo report a vulnerability, see [SECURITY.md](SECURITY.md). Do not open public issues for security concerns.\n\n## License\n\nLicensed under the [Apache License 2.0](LICENSE).\n\nCopyright 2025 Happy Technologies LLC\n\n---\n\n## Trademark Notice\n\nServiceNow&reg; is a registered trademark of ServiceNow, Inc. \"Now\" is a registered trademark of ServiceNow, Inc. All ServiceNow&reg; product names, logos, and brands are property of ServiceNow, Inc.\n\nModel Context Protocol (MCP) is an open standard created by Anthropic, PBC. \"Claude\" is a trademark of Anthropic, PBC.\n\n**Happy MCP Server is an independent, community-driven project.** It is not affiliated with, endorsed by, or sponsored by ServiceNow, Inc. or Anthropic, PBC. This project provides tooling that connects to ServiceNow&reg; instances via their published REST APIs, and implements the open MCP specification. It is not a competitor to any ServiceNow&reg; product or service.\n\nAll other trademarks are the property of their respective owners. See [NOTICE](NOTICE) for full attribution.\n",
  "bytes": 21208,
  "sha": "13099345ba571ce6e366692ac88619b785a71bf2477cd5c7b90a7bf2ca94d8fe",
  "repo_slug": "happy-technologies-llc/mcp-servicenow-nodejs",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_nickzitzer_servicenow_nodejs_d1499091/readme"
}