echelon-ai-labs/servicenow-mcp

A Model Completion Protocol (MCP) server implementation for ServiceNow, allowing Claude to interact with ServiceNow instances.
Overview
This project implements an MCP server that enables Claude to connect to ServiceNow instances, retrieve data, and perform actions through the ServiceNow API. It serves as a bridge between Claude and ServiceNow, allowing for seamless integration.
Features
- Connect to ServiceNow instances using various authentication methods (Basic, OAuth, API Key)
- Query ServiceNow records and tables
- Create, update, and delete ServiceNow records
- Execute ServiceNow scripts and workflows
- Access and query the ServiceNow Service Catalog
- Analyze and optimize the ServiceNow Service Catalog
- Debug mode for troubleshooting
- Support for both stdio and Server-Sent Events (SSE) communication
Installation
Prerequisites
- Python 3.11 or higher
- A ServiceNow instance with appropriate access credentials
Setup
1. Clone this repository:
2. Create a virtual environment and install the package:
3. Create a .env file with your ServiceNow credentials:
Usage
Standard (stdio) Mode
To start the MCP server:
Or with environment variables:
Server-Sent Events (SSE) Mode
The ServiceNow MCP server can also run as a web server using Server-Sent Events (SSE) for communication, which allows for more flexible integration options.
Starting the SSE Server
You can start the SSE server using the provided CLI:
By default, the server will listen on 0.0.0.0:8080. You can customize the host and port:
Connecting to the SSE Server
The SSE server exposes two main endpoints:
- /sse - The SSE connection endpoint
- /messages/ - The endpoint for sending messages to the server
Example
See the examples/sse_server_example.py file for a complete example of setting up and running the SSE server.
Tool Packaging (Optional)
To manage the number of tools exposed to the language model (especially in environments with limits), the ServiceNow MCP server supports loading subsets of tools called "packages". This is controlled via the MCP_TOOL_PACKAGE environment variable.
Configuration
1. **Environment Variable:** Set the MCP_TOOL_PACKAGE environment variable to the name of the desired package.
2. **Package Definitions:** The available packages and the tools they include are defined in config/tool_packages.yaml. You can customize this file to create your own packages.
Behavior
- If MCP_TOOL_PACKAGE is set to a valid package name defined in config/tool_packages.yaml, only the tools listed in that package will be loaded.
- If MCP_TOOL_PACKAGE is **not set** or is empty, the full package (containing all tools) is loaded by default.
- If MCP_TOOL_PACKAGE is set to an invalid package name, the none package is loaded (no tools except list_tool_packages), and a warning is logged.
- Setting MCP_TOOL_PACKAGE=none explicitly loads no tools (except list_tool_packages).
Available Packages (Default)
The default config/tool_packages.yaml includes the following role-based packages:
- service_desk: Tools for incident handling and basic user/knowledge lookup.
- catalog_builder: Tools for creating and managing service catalog items, categories, variables, and related scripting (UI Policies, User Criteria).
- change_coordinator: Tools for managing the change request lifecycle, including tasks and approvals.
- knowledge_author: Tools for creating and managing knowledge bases, categories, and articles.
- platform_developer: Tools for server-side scripting (Script Includes), workflow development, and deployment (Changesets).
- system_administrator: Tools for user/group management and viewing system logs.
- agile_management: Tools for managing user stories, epics, scrum tasks, and projects.
- full: Includes all available tools (default).
- none: Includes no tools (except list_tool_packages).
Introspection Tool
- **list_tool_packages**: Lists all available tool package names defined in the configuration and shows the currently loaded package. This tool is available in all packages except none.
Available Tools
**Note:** The availability of the following tools depends on the loaded tool package (see Tool Packaging section above). By default (full package), all tools are available.
Incident Management Tools
1. **create_incident** - Create a new incident in ServiceNow
2. **update_incident** - Update an existing incident in ServiceNow
3. **add_comment** - Add a comment to an incident in ServiceNow