markdown

ServiceNow Enterprise Control Plane (MCP Server)

This implementation establishes an MCP endpoint that bridges advanced AI reasoning capabilities (like Claude) with the comprehensive functionality exposed by the ServiceNow Platform REST APIs. It acts as a controlled execution layer for automation tasks.

Core Functionality

This server provides robust mechanisms for an AI agent to connect to, query, modify, and manage various components within a target ServiceNow instance. It supports diverse authentication schemas to ensure secure access.

Feature Set

• Secure Connectivity: Supports Basic Auth, OAuth 2.0 flows, and direct API Key authentication against the instance.
• Data Manipulation: Capabilities to Create, Read, Update, and Delete (CRUD) records across multiple ServiceNow tables (e.g., Incidents, Changes, Users).
• Workflow & Script Execution: Tools for invoking or managing workflows and interacting with Script Includes.
• Service Catalog Management: Comprehensive toolset for inspecting, creating, modifying, and optimizing Service Catalog Items and their associated variables and categories.
• Platform Artifact Control: Functions for managing deployment artifacts via Changesets and version control.
• Agile/DevOps Integration: Tools targeting Story, Epic, Scrum Task, and Project lifecycle management within the Agile module.
• Transport Flexibility: Operates via standard input/output (stdio) for CLI invocation or via Server-Sent Events (SSE) for persistent, event-driven communication channels.

Deployment Prerequisites & Setup

Requirements

• Python Runtime Environment (version 3.11 or later).
• Valid credentials and access rights for the target ServiceNow instance.

Initialization Sequence

1. Source Acquisition: bash git clone https://github.com/echelon-ai-labs/servicenow-mcp.git cd servicenow-mcp

2. Environment Setup & Installation: bash python -m venv .venv source .venv/bin/activate # Use .venv\Scripts\activate on Windows pip install -e .

3. Credential Configuration: Establish a .env file containing instance details: env SERVICENOW_INSTANCE_URL=https://your-instance.service-now.com SERVICENOW_USERNAME=your-username SERVICENOW_PASSWORD=your-password SERVICENOW_AUTH_TYPE=basic # Options: basic, oauth, api_key

Operational Modes

1. Standard (Streamed) Mode

Execute the server for direct stdin/stdout interaction:

bash python -m servicenow_mcp.cli

2. Server-Sent Events (SSE) Web Service

Run the server as a persistent web listener (default port 8080):

bash servicenow-mcp-sse --instance-url=... --username=... --password=...

Endpoints Exposed:

• /sse: Primary stream for bidirectional communication.
• /messages/: Endpoint for pushing external commands to the server.

Example SSE Web Server Startup (Python) python from servicenow_mcp.server import ServiceNowMCP from servicenow_mcp.server_sse import create_starlette_app from servicenow_mcp.utils.config import ServerConfig, AuthConfig, AuthType, BasicAuthConfig import uvicorn

config = ServerConfig( instance_url="https://your-instance.service-now.com", auth=AuthConfig( type=AuthType.BASIC, config=BasicAuthConfig(username="your-username", password="your-password") ), debug=True, )

servicenow_mcp = ServiceNowMCP(config) app = create_starlette_app(servicenow_mcp, debug=True)

uvicorn.run(app, host="0.0.0.0", port=8080)

Tool Packaging and Scoping

The system employs a modular packaging structure, controlled by the MCP_TOOL_PACKAGE environment variable, to precisely limit the functions exposed to the language model, which is crucial for adherence to token budget constraints or role-based access control.

• Loading Mechanism: If MCP_TOOL_PACKAGE is set (e.g., export MCP_TOOL_PACKAGE=catalog_builder), only tools defined within that configuration file (config/tool_packages.yaml) are loaded.
• Default Behavior: If unset, the full package (all capabilities) is loaded.
• Introspection: The list_tool_packages utility is always available (unless the none package is explicitly selected) to query available scopes.

Predefined Packages (Role-Based Scope)

• service_desk: Incident response and basic lookup.
• catalog_builder: Service Catalog item creation/modification.
• change_coordinator: Change Request lifecycle management.
• knowledge_author: Knowledge article creation and maintenance.
• platform_developer: Script Include and Changeset operations.
• system_administrator: User/Group lifecycle and log inspection.
• agile_management: Agile Development (Stories, Epics, Scrum).
• full: All tools.
• none: Only list_tool_packages.

Tool Registry

Tool availability is contingent upon the active package.

Incident Operations

1. create_incident: Provision new issue tickets.
2. update_incident: Modify existing ticket attributes.
3. add_comment: Append commentary to a ticket.
4. resolve_incident: Close out a resolved ticket.
5. list_incidents: Retrieve ticket lists.

Service Catalog Management

• Item & Category CRUD: list_catalog_items, get_catalog_item, list_catalog_categories, create_catalog_category, update_catalog_category, move_catalog_items, list_catalogs.
• Variable Administration: create_catalog_item_variable, list_catalog_item_variables, update_catalog_item_variable.

Catalog Refinement Tools

1. get_optimization_recommendations: Audits catalog structure for suggested improvements.
2. update_catalog_item: General item metadata modification.

Change Lifecycle

• create_change_request, update_change_request, list_change_requests, get_change_request_details.
• Workflow Control: add_change_task, submit_change_for_approval, approve_change, reject_change.

Agile Development Suite

• Stories: create_story, update_story, list_stories, create_story_dependency, delete_story_dependency.
• Epics: create_epic, update_epic, list_epics.
• Tasks: create_scrum_task, update_scrum_task, list_scrum_tasks.
• Projects: create_project, update_project, list_projects.

Platform Scripting & Deployment

• Workflows: list_workflows, get_workflow, create_workflow, update_workflow, delete_workflow.
• Script Includes: Management tools for server-side JS definitions.
• Changesets (Deployment): Tools for tracking and deploying configuration updates (list_changesets, commit_changeset, publish_changeset, etc.).

Knowledge Management

Tools for structuring and authoring content: KB creation, category definition, article CRUD, and publishing controls.

Identity & Access Control

• User Ops: User provisioning (create_user, update_user, get_user, list_users).
• Group Ops: Group creation, membership management (create_group, add_group_members, list_groups).

UI Policy Automation

Tools for dynamic form control configuration: create_ui_policy and create_ui_policy_action.

Integration and Configuration Examples

CLI Installation Registration

Registering the server via the specialized CLI, optionally sourcing environment variables:

bash mcp install src/servicenow_mcp/server.py -f .env

Claude Desktop Configuration

To integrate with the local Claude application, modify its configuration file (e.g., ~/Library/Application Support/Claude/claude_desktop_config.json) to reference the Python executable and arguments:

{ "mcpServers": { "ServiceNow": { "command": "/Users/yourusername/dev/servicenow-mcp/.venv/bin/python", "args": ["-m", "servicenow_mcp.cli"], "env": { "SERVICENOW_INSTANCE_URL": "https://your-instance.service-now.com", "SERVICENOW_USERNAME": "your-username", "SERVICENOW_PASSWORD": "your-password", "SERVICENOW_AUTH_TYPE": "basic" } } } }

Interaction Scenarios (Examples)

Incident Handling: * "Provision a critical incident reporting a widespread network failure in the EU data center." * "Augment incident INC0010001 with diagnostic logs and set priority to P1."

Catalog Governance: * "Audit the Hardware catalog and relocate all 'Monitor' assets into a new 'Display Technology' category." * "Insert a mandatory string input field for 'Asset Tag ID' onto the 'Standard Desktop Request' form."

Change Execution: * "Orchestrate a standard change for applying quarterly database security patches scheduled for deployment this Saturday midnight." * "Advance the pending change CHG0012345 to the 'Review' state."

Advanced Documentation & Development

Detailed specifications are structured within the docs/ directory:

• docs/catalog.md: Deep dive into Service Catalog API interactions.
• docs/change_management.md: Governing the change control process tools.
• docs/workflow_management.md: Workflow definition and manipulation.

Troubleshooting Common Failures

• Parameter Type Mismatch (e.g., Change Creation): Errors like argument after ** must be a mapping, not CreateChangeRequestParams indicate that an internal Pydantic model was passed where a raw dictionary was expected. The library attempts automatic unwrapping, but manual dictionary formatting is the robust solution.
• Mandatory Field Omission: Errors like Missing required parameter 'type' necessitate verifying that all documented required inputs (e.g., short_description and type for change requests) are present.
• Authentication Context: Issues involving Cannot find get_headers method... often stem from incorrect parameter sequencing during function calls, though wrapper functions have been updated for better resilience against parameter swapping.

Contribution Guidelines

We welcome enhancements. Please follow the standard fork-commit-PR workflow. Ensure new features align with established coding standards and documentation.

Licensing

Distributed under the permissive MIT License. Consult LICENSE file for specifics.

== Business Tool Context == ServiceNow platforms are quintessential business management tools, centralizing processes across IT Service Management (ITSM), IT Operations Management (ITOM), and IT Business Management (ITBM). This integration layer allows generative AI to directly influence planning, process control, data consolidation, and operational execution within the enterprise, dramatically accelerating the adaptation and optimization referenced in broader business management tool theory.

== Execution Scope Catalog (Default Full Set) ==

• Incident Tools: Ticket CRUD, status updates.
• Catalog Tools: Item/Category/Variable lifecycle management.
• Change Tools: Full control over Normal, Standard, and Emergency changes.
• Agile Tools: Managing backlog items (Stories, Epics) and related tasks.
• Platform Tools: Script Include, Workflow, and Changeset administrative functions.
• User Tools: Identity management for Users and Groups.
• Knowledge Tools: Article creation and categorization.