servicenow-platform-mcp

A comprehensive Model Context Protocol (MCP) server for ServiceNow. Provides 14 unified tools in 11 tool groups 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).

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. Writes use preview-then-apply by default; callers can explicitly set preview=false for an immediate write.
• 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"
)

List mode requires an explicit field projection. Use a small field set for normal reads. Use fields="*" only when the full record is intentional. sys_id is always included. Successful responses include selection metadata describing the projection.

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