Happy MCP Server

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:

# npm
npm uninstall servicenow-mcp-server && npm install happy-platform-mcp

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

Features

• Multi-Instance Support — Connect to multiple ServiceNow® instances simultaneously with per-request routing

• OAuth 2.0 & Basic Auth — Per-instance authentication with Resource Owner Password Credentials grant, automatic token refresh, and seamless fallback

• 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

• 53 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 18+

• 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

Configure Instances

Option A: Multi-Instance (Recommended)

cp config/servicenow-instances.json.example config/servicenow-instances.json

Edit config/servicenow-instances.json:

{
  "instances": [
    {
      "name": "dev",
      "url": "https://dev123456.service-now.com",
      "username": "admin",
      "password": "your-password",
      "default": true
    },
    {
      "name": "prod",
      "url": "https://prod789012.service-now.com",
      "authType": "oauth",
      "grantType": "client_credentials",
      "clientId": "your-oauth-client-id",
      "clientSecret": "your-oauth-client-secret"
    }
  ]
}

Each instance can use "authType": "basic" (default) or "authType": "oauth". OAuth instances require clientId and clientSecret from your ServiceNow OAuth Application Registry. See Authentication for details.

Option B: Single Instance (via Environment)

cp .env.example .env
# Edit .env with your credentials

Start the Server

# HTTP/SSE transport
npm run dev

# Stdio transport (for Claude Desktop)
npm run stdio

Verify

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

Multi-Instance Routing

All tools accept an optional instance parameter:

// Uses default instance
SN-List-Incidents({ "limit": 10 })

// Routes to a specific instance
SN-List-Incidents({ "instance": "prod", "limit": 10 })

Tool Overview

Examples

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

// Create a record
SN-Create-Incident({ "short_description": "Email service down", "urgency": 1 })

// Natural language search
SN-NL-Search({ "table_name": "incident", "query": "high priority incidents assigned to me" })

// Background script execution (automated via sys_trigger)
SN-Execute-Background-Script({ "script": "gs.info('Hello');" })

// Update set management
SN-Set-Update-Set({ "update_set_sys_id": "abc123..." })

// Batch operations
SN-Batch-Update({ "updates": [{ "table": "incident", "sys_id": "id1", "data": {...} }] })

// Service Catalog AI-submission workflow
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" } })

// ServiceNow Docs local search workflow
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:

// Download script to local file
SN-Sync-Script-To-Local({
  "script_sys_id": "abc123...",
  "local_path": "/scripts/business_rules/validate_incident.js"
})

// Watch for changes and auto-sync
SN-Watch-Script({
  "local_path": "/scripts/business_rules/validate_incident.js",
  "script_sys_id": "abc123..."
})

Natural Language Search

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 config/servicenow-instances.json or HAPPY_DOCS_ENABLE_LOCAL_INDEX=true.

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

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.

Claude Desktop Integration

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

Basic Auth:

{
  "mcpServers": {
    "happy-mcp-server": {
      "command": "npx",
      "args": ["-y", "happy-platform-mcp"],
      "env": {
        "SERVICENOW_INSTANCE_URL": "https://your-instance.service-now.com",
        "SERVICENOW_USERNAME": "your-username",
        "SERVICENOW_PASSWORD": "your-password"
      }
    }
  }
}

OAuth:

{
  "mcpServers": {
    "happy-mcp-server": {
      "command": "npx",
      "args": ["-y", "happy-platform-mcp"],
      "env": {
        "SERVICENOW_INSTANCE_URL": "https://your-instance.service-now.com",
        "SERVICENOW_USERNAME": "your-username",
        "SERVICENOW_PASSWORD": "your-password",
        "SERVICENOW_AUTH_TYPE": "oauth",
        "SERVICENOW_CLIENT_ID": "your-client-id",
        "SERVICENOW_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Or if installed from source, use "command": "node" with "args": ["/path/to/happy-platform-mcp/src/stdio-server.js"] and "cwd": "/path/to/happy-platform-mcp".

For multi-instance configurations, use config/servicenow-instances.json instead of environment variables. See Configure Instances.

Restart Claude Desktop after editing the config.

Authentication

Happy MCP Server supports two authentication methods per instance. Both can coexist — instance A can use basic auth while instance B uses OAuth.

Basic Auth (Default)

No extra configuration needed. Provide username and password:

{
  "name": "dev",
  "url": "https://dev123456.service-now.com",
  "username": "admin",
  "password": "your-password",
  "default": true
}

OAuth 2.0

Supports both Client Credentials (recommended) and Resource Owner Password Credentials grant types. Tokens are automatically requested, cached, and refreshed.

Client Credentials (recommended) — no user credentials needed, ideal for service-to-service integrations and federated identity environments:

{
  "name": "prod",
  "url": "https://prod789012.service-now.com",
  "authType": "oauth",
  "grantType": "client_credentials",
  "clientId": "your-oauth-client-id",
  "clientSecret": "your-oauth-client-secret"
}

Resource Owner Password Credentials — for cases where user context is required:

{
  "name": "staging",
  "url": "https://staging.service-now.com",
  "authType": "oauth",
  "grantType": "password",
  "clientId": "your-oauth-client-id",
  "clientSecret": "your-oauth-client-secret",
  "username": "integration_user",
  "password": "your-password"
}

If grantType is omitted, it defaults to client_credentials when no username is provided, or password when username is present.

ServiceNow setup:

1. Navigate to System OAuth > Application Registry

2. Click New and select Create an OAuth API endpoint for external clients

3. Set a name (e.g., "MCP Server") and note the generated Client ID and Client Secret

4. Add those values to your instance configuration

How it works:

• On first API call, requests an access token from /oauth_token.do

• Caches the token and automatically refreshes it before expiry (30-second buffer)

• On 401 responses, transparently refreshes the token and retries the request once

• Falls back to a fresh token grant if the refresh token is expired

The scope field is optional and defaults to ServiceNow's standard scope.

Architecture

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

# Run tests
npm test

# Watch mode
npm run test:watch

# Coverage
npm run test:coverage

# MCP Inspector
npm run inspector

Troubleshooting

Connection Issues

# Test connectivity to your ServiceNow instance
curl -u username:password https://your-instance.service-now.com/api/now/table/incident?sysparm_limit=1

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

Common Problems

• Multi-instance not working: Verify config/servicenow-instances.json is valid JSON with one "default": true instance. Restart after changes.

• Tools not appearing: Check MCP Inspector connection and server logs.

• Auth failures: Test credentials in browser first. Ensure the user has required roles.

• SSE disconnects in Docker: Enable keepalive (default 15s). See docs/SSE_SETUP_GUIDE.md.

Debug Mode

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 docs/MCP_Tool_Limitations.md 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.

Copyright 2025 Happy Technologies LLC

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.