Servicenow Nodejs

Happy MCP Server

Model Context Protocol Server for the ServiceNow® Platform

A metadata-driven MCP server with 60 tools that work on any table, built-in schema for 94 core tables, multi-instance support, natural language search, and local script development.

Website | GitHub | npm | Tools | Get updates | Discussions | Contributing | Support

---

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

`

Stay in the loop

• Release notes, security advisories, and workshop dates: happy-tech.biz/mcp. One short email when something ships or needs patching. No drip campaigns.
• Questions, ideas, show and tell: GitHub Discussions
• Running it at your company? Add yourself to the users list and we will list you below.
• Talk to us: happy-tech.biz/contact.html for supported releases, team enablement, and AI-native development on the ServiceNow® platform.

Who is using Happy MCP

Your company belongs here. Open a two-minute issue and we will add the row.

Support

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

• GitHub Sponsors
• Buy Me a Coffee

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
• Any Table — Generic tools work on any table, with built-in schema metadata for 94 core tables across ITSM, CMDB, Service Catalog, Platform Development, and Flow Designer
• 60 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

npx happy-platform-mcp

Or install globally:

npm install -g happy-platform-mcp

Install from Source

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 , 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:

npm install -g happy-platform-mcp

SERVICENOW_INSTANCE=dev happy-platform-mcp

An MCP host can use the global command:

{

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

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:

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:

{

"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)

cp .env.example .env

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

Start the Server

# Stdio transport (for Claude Desktop); no HTTP token involved

npm run stdio

HTTP/SSE transport; refuses to start without a valid bearer token

export HAPPY_MCP_API_TOKEN="$(openssl rand -hex 32)" npm run dev

HTTP Transport Security

The HTTP/SSE transport is built for one trusted operator, a single principal. Whoever holds HAPPY_MCP_API_TOKEN can use every ServiceNow credential configured on the server, so ServiceNow ACLs on those accounts still decide what they can do. HTTP authentication doesn't replace them. Shared multi-user hosting isn't supported: several people or tenants sharing one server or token get no per-user identity, isolation or authorization. Run one server per operator.

• A token is required on every listener. HTTP startup fails unless HAPPY_MCP_API_TOKEN is 32 random bytes encoded as 64 hex characters (openssl rand -hex 32) or 43 base64url characters. Loopback and embedded createHttpApp use are no exception. The server checks the encoding but can't measure randomness, so always generate the value. Keep it in a secret store or an untracked .env, never commit or log it, and rotate it by restarting with a new value. Stdio doesn't use it.
• Every route authenticates. /health, /instances, GET /mcp and POST /mcp all require exactly one Authorization: Bearer header. The token is compared in constant time. Requests are rejected before body parsing or session setup.
• Failed attempts are throttled. After 10 failed attempts from one peer address within a minute, that peer receives 429 with Retry-After until the window ends. The throttle is checked before the token, so a blocked peer is refused even with the right token. The budget lives in process memory: it resets on restart, isn't shared between processes, and only tracks a bounded number of peers. Behind a reverse proxy, or Docker port publishing where host clients can share one gateway address, every client shares one budget, so any unauthenticated client that can reach the endpoint can lock the operator out with ten bad requests a minute. Restrict who can reach the proxy and rate-limit there.
• Host and Origin are checked (DNS-rebinding protection). Host must name the listener (127.0.0.1: , localhost: or [::1]: on loopback, otherwise the bound address and port) or exactly match a HAPPY_MCP_ALLOWED_HOSTS entry. Requests without Origin, as native MCP clients send them, are allowed. A present Origin must exactly match a `HAPPY_MCP_A