servicenow-platform-mcp

A comprehensive Model Context Protocol (MCP) server for ServiceNow. Provides 12 unified tools for platform introspection, change intelligence, debugging, record management, and automated investigations.

Quick Start

1. Set environment variables:

export SERVICENOW_INSTANCE_URL=https://your-instance.service-now.com
export SERVICENOW_USERNAME=admin
export SERVICENOW_PASSWORD=your-password

2. Run the server:

uvx servicenow-platform-mcp

3. Connect your MCP client (see Configuration below).

Related MCP server: snow-mcp

Configuration

OpenCode

Add to ~/.config/opencode/opencode.json:

{
  "mcp": {
    "servicenow": {
      "type": "local",
      "command": ["uvx", "servicenow-platform-mcp"],
      "environment": {
        "SERVICENOW_INSTANCE_URL": "https://your-instance.service-now.com",
        "SERVICENOW_USERNAME": "admin",
        "SERVICENOW_PASSWORD": "your-password"
      }
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "servicenow": {
      "command": "uvx",
      "args": ["servicenow-platform-mcp"],
      "env": {
        "SERVICENOW_INSTANCE_URL": "https://your-instance.service-now.com",
        "SERVICENOW_USERNAME": "admin",
        "SERVICENOW_PASSWORD": "your-password"
      }
    }
  }
}

VS Code / Cursor

Add to .vscode/mcp.json:

{
  "servers": {
    "servicenow": {
      "command": "uvx",
      "args": ["servicenow-platform-mcp"],
      "env": {
        "SERVICENOW_INSTANCE_URL": "https://your-instance.service-now.com",
        "SERVICENOW_USERNAME": "admin",
        "SERVICENOW_PASSWORD": "your-password"
      }
    }
  }
}

Generic stdio

SERVICENOW_INSTANCE_URL=https://your-instance.service-now.com \
SERVICENOW_USERNAME=admin \
SERVICENOW_PASSWORD=your-password \
uvx servicenow-platform-mcp

Environment Variables

The server reads from .env and .env.local files automatically.

AI Agent Setup

Copy and paste this prompt to your AI agent (Claude Code, Cursor, OpenCode, etc.):

Install and configure servicenow-platform-mcp by following the instructions here:
https://raw.githubusercontent.com/Xerrion/servicenow-platform-mcp/refs/heads/main/INSTALL.md

Or read the Installation Guide directly. For usage examples and patterns, see Agent Recipes.

Key Features

• Platform Introspection - Describe table schemas with describe and query records with query using encoded queries.

• Record Management - Unified record_write and record_apply tools for create, update, and delete with a mandatory preview-then-apply safety pattern.

• Script-Bearing Records - Write Business Rules, Script Includes, UI Pages, Widgets, UI Macros, ACLs, and any other table whose dictionary fields carry executable script or markup, all via record_write with local script file support and per-field targeting (script_field). Script fields are discovered at runtime from sys_dictionary — no hardcoded artifact catalog. Read the same surface back via record_read, or enumerate a table's script fields with describe(action='list_script_fields', table='<table>').

• Attachment Operations - Unified attachment for read operations and attachment_write for mutations.

• Investigations - Automated analysis of system health, stale automations, performance bottlenecks, and more via investigate.

• Label Resolution - Map human-readable choice labels to underlying values automatically with resolve_choice.

• Service Catalog - Dispatcher-based service_catalog tool for browsing and ordering.

Example Usage

Describe a Table

await describe(table="incident")

Query Records

# Fetch high priority incidents using an encoded query
await query(
    table="incident",
    encoded_query="active=true^priority=1",
    fields="number,short_description,priority"
)

Tool Packages

Control which tools are loaded with MCP_TOOL_PACKAGE.

Custom packages are supported via comma-separated tool names: MCP_TOOL_PACKAGE="query,describe,attachment".

Safety

• Table Deny List - Blocks access to sensitive system tables (sys_user_has_password, sys_credentials, etc.).

• Sensitive Field Masking - Passwords, tokens, and secrets are automatically masked in responses.

• Write Gating - All mutations are blocked when SERVICENOW_ENV is set to prod or production.

• Query Safety - Enforces row limits and mandatory date filters on high-volume system tables.

These guardrails reduce risk but are not a guarantee - always validate in a sub-production environment.

See the Safety & Policy wiki page for complete details.

Development

git clone https://github.com/Xerrion/servicenow-platform-mcp.git
cd servicenow-platform-mcp
uv sync --group dev
uv run pytest                  # Run tests
uv run ruff check .            # Lint
uv run ruff format .           # Format
uv run mypy src/               # Type check

License

MIT