ServiceNow CMDB MCP Server

A Python MCP server that connects AI assistants (Claude Code, Claude Desktop, Cursor) to a ServiceNow CMDB instance via natural language. Enables querying, dependency analysis, health auditing, CI lifecycle management, and configurable inspection — all through the Model Context Protocol.

What makes this different

• Deep CMDB focus with relationship traversal, impact analysis, path finding, and dependency mapping
• display_value support — reference fields return human-readable names, not opaque sys_ids
• ASCII tree visualization for dependency graphs directly in the terminal
• Dynamic schema powered by the Data Model Navigator plugin (no hardcoded class hierarchies)
• Full configurable inspection (business rules, flows, flow logic, client scripts, script includes, ACLs) with credential redaction
• Discovery, IRE rules, and import set visibility
• Two-phase write confirmation for safe CI mutations
• Rich server instructions that guide LLM behavior (workflow patterns, smart defaults, disambiguation)
• Tool annotations for smart auto-approval in Claude Code

Requirements

• Python 3.11+
• uv package manager
• ServiceNow instance (Xanadu+) with an OAuth 2.0 application and service account

Setup

1. Clone the repository and install dependencies:

uv sync

2. Copy .env.example to .env and fill in your ServiceNow credentials:

cp .env.example .env

SN_INSTANCE_URL=https://your-instance.service-now.com
SN_CLIENT_ID=your-oauth-client-id
SN_CLIENT_SECRET=your-oauth-client-secret
SN_USERNAME=your-service-account
SN_PASSWORD=your-password

3. Run the server:

uv run servicenow-cmdb-mcp

Claude Code integration

Add to your .mcp.json in the project root:

{
  "mcpServers": {
    "servicenow-cmdb": {
      "command": "uv",
      "args": ["run", "servicenow-cmdb-mcp"],
      "cwd": "/path/to/mcp-cmdb",
      "env": {
        "SN_INSTANCE_URL": "https://your-instance.service-now.com",
        "SN_CLIENT_ID": "your-oauth-client-id",
        "SN_CLIENT_SECRET": "your-oauth-client-secret",
        "SN_USERNAME": "your-service-account",
        "SN_PASSWORD": "your-password"
      }
    }
  }
}

Recommended ServiceNow roles

The service account needs these roles for full functionality:

Role	What it unlocks
cmdb_read	CMDB CI queries, relationships, health tools
itil	Standard ITSM tables, basic platform access
fd_read	Flow Designer read access (flow details, triggers)
personalize	Client scripts, UI policies

Optional roles for deeper inspection:

Role	What it unlocks
flow_designer	Flow overview listing
script_include_admin	Script include read access
business_rule_admin	Business rule scripts

Tools (38 total)

Domain	Tools	Description
Queries	search_cis, query_cis_raw, get_ci_details, count_cis, suggest_table, list_ci_classes, describe_ci_class	Search, inspect, and explore CMDB classes. Supports display_value for human-readable reference fields
Relationships	get_ci_relationships, find_related_cis, list_relationship_types, get_dependency_tree, get_impact_summary, find_ci_path	Traverse CI relationships, visualize dependency trees (ASCII format), find shortest paths between CIs. Supports class_filter to focus on specific CI types
Health	find_orphan_cis, find_duplicate_cis, find_stale_cis, cmdb_health_summary	Audit CMDB data quality
Mutations	preview_ci_create, confirm_ci_create, preview_ci_update, confirm_ci_update	Safe two-phase CI writes
Configurables	get_business_rules, get_flows, get_flow_details, get_client_scripts, get_acls, get_script_includes, analyze_configurables	Inspect automation, flow logic, and security config
Discovery	list_discovery_schedules, get_discovery_status, get_discovery_errors	Monitor discovery operations
IRE	get_identification_rules, get_reconciliation_rules, explain_duplicate	Inspect identification and reconciliation
Imports	list_data_sources, get_import_set_runs, get_transform_errors	Monitor data imports and transforms
Utilities	check_connection, refresh_metadata_cache, _diag_probe_table	Connectivity check, cache management, table access diagnostics

Key features

Display values

Query tools support display_value="true" to return human-readable names instead of sys_ids for reference fields (location, assigned_to, company, etc.).

Tree visualization

get_dependency_tree supports format="ascii_tree" to return pre-rendered text trees, and class_filter to show only specific CI types (e.g., servers only, no disks/memory).

Flow inspection

get_flow_details parses the internal label_cache from Flow Designer to show flow triggers, steps, referenced tables, and data flow — without needing admin access.

Path finding

find_ci_path finds the shortest relationship path between any two CIs using BFS traversal.

Development

# Run unit tests
uv run pytest tests/ -v

# Run smoke tests (requires live ServiceNow instance)
uv run python smoke_tests/smoke_test.py

# Type check
uv run mypy src/

# Lint
uv run ruff check src/

# Fallback if uv run fails with "file in use" on Windows
.venv/Scripts/python.exe -m pytest tests/ -v

Architecture

See ARCHITECTURE.md for the full design document covering authentication, security, tool patterns, and API usage.

Tech stack

• FastMCP (mcp[cli]) — MCP server framework with decorator-based tool registration
• httpx — Async HTTP client for ServiceNow REST APIs
• pydantic / pydantic-settings — Configuration and validation
• OAuth 2.0 — Password grant against ServiceNow /oauth_token.do
• STDIO transport — Local deployment for Claude Code / Claude Desktop / Cursor