Happy MCP Server

Model Context Protocol Server for the ServiceNow® Platform

A metadata-driven MCP server that auto-generates 480+ tools across 160+ tables, with multi-instance support, natural language search, and local script development.

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:
bash
# npm
npm uninstall servicenow-mcp-server && npm install happy-platform-mcp

# Docker
docker pull nczitzer/happy-platform-mcp:latest

Support

If you find this project useful, consider supporting its development. Contributions support Happy Technologies LLC.

Features

Multi-Instance Support — Connect to multiple ServiceNow® instances simultaneously with per-request routing
OAuth 2.0 & Basic Auth — Per-instance Client Credentials, Resource Owner Password Credentials, and per-user Authorization Code with PKCE
Intelligent Schema Discovery — Automatically discovers table structures and relationships at runtime
160+ Tables — Complete coverage including ITSM, CMDB, Service Catalog, Platform Development, and Flow Designer
55 MCP Tools — Generic CRUD operations that work on any table, plus specialized convenience tools
Batch Operations — 43+ parallel operations tested successfully
Local Script Development — Sync scripts with Git, watch mode for continuous development
Natural Language Search — Query using plain English instead of encoded queries
MCP Resources — 8 read-only resource URIs for quick lookups and documentation
Background Script Execution — Automated server-side script execution via sys_trigger
Service Catalog AI-Submission — Browse, inspect, and submit Service Catalog forms programmatically
ServiceNow Docs Search — Optional GitHub-backed docs retrieval and local SQLite FTS search over official ServiceNowDocs markdown

Quick Start

Prerequisites

Node.js 20+
One or more ServiceNow® instances with REST API access
Valid credentials for each instance

Install from npm

Terminal

npx happy-platform-mcp

Or install globally:

Terminal

npm install -g happy-platform-mcp

Install from Source

bash

git clone https://github.com/Happy-Technologies-LLC/happy-platform-mcp.git
cd happy-platform-mcp
npm install
# Source checkout: use node src/cli.js <command>, or npm link first.
node src/cli.js instance list

Start the stdio server

After a global install, happy-platform-mcp with no arguments starts the stdio MCP server:

Terminal

npm install -g happy-platform-mcp
SERVICENOW_INSTANCE=dev happy-platform-mcp

An MCP host can use the global command:

config.json

{
  "mcpServers": {
    "happy-mcp-server": {
      "command": "happy-platform-mcp",
      "env": { "SERVICENOW_INSTANCE": "dev" }
    }
  }
}

Or use npx with command: "npx" and args: ["-y", "happy-platform-mcp"]. From a source checkout, use node src/stdio-server.js; source CLI commands use node src/cli.js instance ....

Configure Instances

Recommended: register metadata with the local CLI

The CLI inherits the environment of the process that launches it. The CLI does not auto-load .env; .env loading applies to the server/stdio process only. For CLI use, export HAPPY_CONFIG_PATH in the shell (or set it in the MCP host environment when the host launches the CLI). The actual default registry path on every OS is <homedir>/.config/happy-platform-mcp/instances.json, using native path separators for that OS.

Credentials are prompted locally, masked, and stored in the operating system keychain. A new CLI-written version 1 registry contains instance metadata and canonical credentialRef values only; it does not contain plaintext credentials. Legacy plaintext registry files are read-only compatibility inputs, and the singular SERVICENOW_* environment fallback is retained only for backward compatibility.

bash

happy-platform-mcp instance add
happy-platform-mcp instance list
happy-platform-mcp instance test dev
happy-platform-mcp instance update dev
happy-platform-mcp instance remove dev
happy-platform-mcp instance migrate

instance add prompts once for the credentials required by the selected auth mode and stores them before registering metadata. instance credential set is only for rotating an existing credential or completing a metadata-only MCP registration. instance update changes metadata only. Authentication changes require instance remove followed by instance add. Secret prompts never put values in command arguments, logs, or MCP messages. These prompts require an interactive local TTY. In non-TTY automation, use a pre-provisioned OS keychain entry and run metadata-only commands; the CLI will not read secrets from stdin or silently fall back to plaintext.

To select a different metadata registry for the CLI, export HAPPY_CONFIG_PATH before invoking it:

server.ts

export HAPPY_CONFIG_PATH="$HOME/.config/happy-platform-mcp/instances.json"
happy-platform-mcp instance list

For an MCP server/stdio host, set the same variable in the host environment:

config.json

{
  "env": {
    "HAPPY_CONFIG_PATH": "~/.config/happy-platform-mcp/instances.json"
  }
}

HAPPY_CONFIG_PATH supports ~ and relative paths. For migration, automatic package-legacy -> user-registry migration is available only when the resolver selects the package-relative config/servicenow-instances.json as readPath and the distinct default user registry as writePath. HAPPY_CONFIG_PATH normally selects both readPath and writePath and must point to a metadata-only version 1 registry. If it points to a plaintext source (the same file), the CLI refuses before any keychain write; source bytes and keychain entries remain unchanged. Choose a distinct HAPPY_CONFIG_PATH target, or unset it for the automatic workflow. Never copy secrets into command arguments. For a non-package legacy source, use a controlled distinct source/target workflow or manually use instance add and the masked instance credential set prompt.

SN-Register-Instance normally applies a live registry reload and does not require a restart. Restart the MCP server only for docs-only mode or when the reload fails.

Legacy compatibility: config/servicenow-instances.json is a read-only legacy migration input. The singular SERVICENOW_* environment variables are the backward-compatible single-instance fallback only when no registry is available. The package-relative file is not the CLI's writable location.

Option B: Single Instance (legacy environment fallback)

bash

cp .env.example .env
# Server/stdio only: set legacy SERVICENOW_* variables in .env.

Start the Server

bash

# HTTP/SSE transport
npm run dev

# Stdio transport (for Claude Desktop)
npm run stdio

HTTP/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>.

Verify

Terminal

curl http://localhost:3000/health
curl http://localhost:3000/instances

# Required when HAPPY_MCP_API_TOKEN is set
curl -H "Authorization: Bearer $HAPPY_MCP_API_TOKEN" http://localhost:3000/health

Multi-Instance Routing

Every 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.

At 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.

javascript

// Uses this session client's current implicit target
await client.callTool({
  name: 'SN-Query-Table',
  arguments: { table_name: 'incident', limit: 10 }
});

// Safely query dev and prod concurrently
await Promise.all([
  client.callTool({
    name: 'SN-Query-Table',
    arguments: { table_name: 'incident', instance: 'dev', limit: 10 }
  }),
  client.callTool({
    name: 'SN-Query-Table',
    arguments: { table_name: 'incident', instance: 'prod', limit: 10 }
  })
]);

Tool Overview

Category	Tools	Description
Generic CRUD	7	Query, Create, Get, Update on any table
Specialized ITSM	8	Incident, Change, Problem convenience wrappers
Convenience	10	Add-Comment, Add-Work-Notes, Assign, Resolve, Close
Natural Language	1	Query using plain English
Update Sets	6	Set, list, move, clone, inspect update sets
Scripts	2	Execute background scripts, create fix scripts
Script Sync	3	Sync scripts with local files, watch mode
Workflows	4	Create workflows, activities, transitions
Batch	2	Batch create/update across tables
Schema	3	Table schemas, field info, relationships
Service Catalog	4	Browse, inspect, and submit catalog forms
ServiceNow Docs	5	Discover, sync, search, and retrieve official ServiceNowDocs markdown
Resources	8	Read-only URIs for table lists, field info

Examples

The following transport-neutral examples show an MCP tool name followed by its arguments:

text

SN-Query-Table
{ "table_name": "incident", "query": "active=true^priority=1", "limit": 10 }

SN-Create-Incident
{ "short_description": "Email service down", "urgency": 1 }

SN-NL-Search
{ "table_name": "incident", "query": "high priority incidents assigned to me" }

SN-Execute-Background-Script
{ "script": "gs.info('Hello');" }

SN-Set-Update-Set
{ "update_set_sys_id": "abc123..." }

SN-Batch-Update
{ "updates": [{ "table": "incident", "sys_id": "id1", "data": { "state": 2 } }] }

SN-Catalog-Search-Items
{ "keyword": "VPN access" }
SN-Catalog-Get-Item
{ "sys_id": "<catalog_item_sys_id>" }
SN-Catalog-Submit
{ "sys_id": "<catalog_item_sys_id>", "variables": { "requested_for": "jsmith", "justification": "Project X" } }

SN-Docs-Families
{}
SN-Docs-Sync
{ "family": "australia" }
SN-Docs-Search
{ "query": "create a Flow Designer action", "family": "australia" }

Local Script Development

Develop scripts locally with version control and automatic sync:

text

SN-Sync-Script-To-Local
{
  "script_sys_id": "abc123...",
  "local_path": "/scripts/business_rules/validate_incident.js"
}

SN-Watch-Script
{
  "local_path": "/scripts/business_rules/validate_incident.js",
  "script_sys_id": "abc123..."
}

Natural Language Search

text

SN-NL-Search
{
  "table_name": "incident",
  "query": "active high priority incidents that are unassigned"
}

Supports 15+ patterns including field comparisons, text searches, date ranges, logical operators, and ordering.

ServiceNow Docs Search

Happy 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.

text

SN-Register-Instance
{ "name": "dev", "url": "https://your-instance.service-now.com", "username": "your-username" }

SN-Docs-Families
{}
SN-Docs-Status
{}
SN-Docs-Sync
{ "family": "australia" }
SN-Docs-Search
{ "query": "update set best practices", "family": "australia", "limit": 5 }
SN-Docs-Get
{ "family": "australia", "path": "platform/example.md" }

SN-Register-Instance accepts metadata only. It never accepts passwords, client secrets, or other secret fields. If a required local credential is missing, its response gives the exact happy-platform-mcp instance credential set ... command to run locally. Registration persists metadata, but a docs-only server must be restarted before live ServiceNow tools are enabled.

SQLite 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.

For 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.

Runtime instance selection

Registration and runtime selection are separate:

Registration persists an available named instance in the registry.
SERVICENOW_INSTANCE chooses the stdio startup default only.
SN-Set-Instance changes the sequential session's shared implicit target in memory; it does not edit the registry.
The optional per-call instance argument selects an isolated request target, so concurrent calls can route to different instances without racing the sequential target.

Claude Desktop Integration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

For a global install, no arguments starts stdio:

config.json

{
  "mcpServers": {
    "happy-mcp-server": {
      "command": "happy-platform-mcp",
      "env": { "SERVICENOW_INSTANCE": "dev" }
    }
  }
}

For an ephemeral install, use command: "npx" with args: ["-y", "happy-platform-mcp"]:

config.json

{
  "mcpServers": {
    "happy-mcp-server": {
      "command": "npx",
      "args": ["-y", "happy-platform-mcp"],
      "env": {
        "HAPPY_CONFIG_PATH": "~/.config/happy-platform-mcp/instances.json"
      }
    }
  }
}

The registry setting points to metadata; credentials remain in the local OS keychain. HAPPY_CONFIG_PATH is optional with the default user path and must be set before the server starts. For source installs, use node src/stdio-server.js in the host config and node src/cli.js instance <command> for CLI operations. Restart Claude Desktop after editing its config.

Authentication

Happy MCP Server supports three credential flows per instance. Interactive instance add captures each required secret once, stores it in the OS keychain, and registers the metadata. Use instance credential set later only to rotate an existing credential or complete metadata-only MCP registration. Never place secrets in JSON or command arguments.

Global CLI: dev basic authentication

bash

happy-platform-mcp instance add
# Select Basic authentication; set the name to dev, enter URL and username,
# then enter the masked password when prompted. The command stores it once.
happy-platform-mcp instance test dev

Global CLI: prod OAuth client credentials

bash

happy-platform-mcp instance add
# Select OAuth -> Client credentials; set the name to prod, enter URL and
# client ID, then enter the masked client secret. The command stores it once.
happy-platform-mcp instance test prod

OAuth password grant

bash

happy-platform-mcp instance add
# Select OAuth -> Password grant; enter URL, client ID, and username, then
# enter both masked prompts. The command stores both credentials once.
happy-platform-mcp instance test password-prod

Password grant credentialRef must be an object containing both canonical references:

json

"credentialRef": {
  "password": "keychain:instance/password-prod/password",
  "clientSecret": "keychain:instance/password-prod/client-secret"
}

Public authorization code with PKCE

bash

happy-platform-mcp instance add
# Select OAuth -> Authorization code and enter URL, client ID,
# authorize URL, token URL, redirect port, and callback path.
happy-platform-mcp instance test public-dev

Public authorization-code metadata requires no credentialRef or client secret. The first test/API call opens the browser flow and stores its refresh token in the OS keychain.

Architecture

Code

src/
├── server.js                     # Express HTTP server (SSE transport)
├── stdio-server.js               # Stdio transport (Claude Desktop)
├── mcp-server-consolidated.js    # MCP tool registration & routing
├── servicenow-client.js          # REST API client
└── config-manager.js             # Multi-instance configuration

config/
└── servicenow-instances.json     # Instance configuration

docs/
├── API_REFERENCE.md              # Complete tool reference
├── SETUP_GUIDE.md                # Detailed setup instructions
└── research/                     # Technical research & discoveries

Testing

bash

# Run tests
npm test

# Watch mode
npm run test:watch

# Coverage
npm run test:coverage

# MCP Inspector
npm run inspector

Troubleshooting

Connection Issues

bash

# Test configured credentials without exposing them in shell history.
happy-platform-mcp instance test <instance-name>

# Check server health
curl http://localhost:3000/health

Common Problems

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.
Tools not appearing: Check MCP Inspector connection and server logs.
Auth failures: Run happy-platform-mcp instance test <instance-name> and verify the local keychain credential reference and required ServiceNow roles.
SSE disconnects in Docker: Enable keepalive (default 15s). See docs/SSE_DOCKER_SETUP.md.

Debug Mode

bash

DEBUG=true npm run dev

Known Limitations

Flow Designer logic blocks cannot be created via REST API (use the UI)
Flow compilation/validation must be done in the UI
UI Policy Actions linking requires a background script workaround

See the API reference and tool-specific guides under docs/ for details.

Acknowledgments

This project was inspired by the Echelon AI Labs ServiceNow MCP Server. We are grateful for their pioneering work in bringing MCP capabilities to the ServiceNow® platform.

Contributing

See CONTRIBUTING.md for guidelines. All contributors must sign a CLA.

Security

To report a vulnerability, see SECURITY.md. Do not open public issues for security concerns.

License

Licensed under the Apache License 2.0.

Trademark Notice

ServiceNow® is a registered trademark of ServiceNow, Inc. "Now" is a registered trademark of ServiceNow, Inc. All ServiceNow® product names, logos, and brands are property of ServiceNow, Inc.

Model Context Protocol (MCP) is an open standard created by Anthropic, PBC. "Claude" is a trademark of Anthropic, PBC.

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® instances via their published REST APIs, and implements the open MCP specification. It is not a competitor to any ServiceNow® product or service.

All other trademarks are the property of their respective owners. See NOTICE for full attribution.