ServiceNow

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:

   git clone https://github.com/yourusername/servicenow-mcp.git
   cd servicenow-mcp
   

2. Create a virtual environment and install the package:

   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   pip install -e .
   

3. Create a .env file with your ServiceNow credentials:

   SERVICENOW_INSTANCE_URL=https://your-instance.service-now.com
   SERVICENOW_USERNAME=your-username
   SERVICENOW_PASSWORD=your-password
   SERVICENOW_AUTH_TYPE=basic  # or oauth, api_key
   

Usage# Standard (stdio) Mode

To start the MCP server:

python -m servicenow_mcp.cli

Or with environment variables:

SERVICENOW_INSTANCE_URL=https://your-instance.service-now.com SERVICENOW_USERNAME=your-username SERVICENOW_PASSWORD=your-password SERVICENOW_AUTH_TYPE=basic python -m servicenow_mcp.cli
```\n\n### 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.\n\n#### Starting the SSE Server
You can start the SSE server using the provided CLI:
```python
servicenow-mcp-sse --instance-url=https://your-instance.service-now.com --username=your-username --password=your-password

By default, the server will listen on 0.0.0.0:8080. You can customize the host and port:

servicenow-mcp-sse --host=127.0.0.1 --port=8000
```\n\n#### 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

## 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.
   ```bash
   export MCP_TOOL_PACKAGE=catalog_builder

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.

Authentication Methods# Basic Authentication

SERVICENOW_AUTH_TYPE=basic
SERVICENOW_USERNAME=your-username
SERVICENOW_PASSWORD=your-password
```\n\n### OAuth Authentication
```bash
SERVICENOW_AUTH_TYPE=oauth
SERVICENOW_CLIENT_ID=your-client-id
SERVICENOW_CLIENT_SECRET=your-client-secret
SERVICENOW_TOKEN_URL=https://your-instance.service-now.com/oauth_token.do
```\n\n### API Key Authentication
```bash
SERVICENOW_AUTH_TYPE=api_key
SERVICENOW_API_KEY=your-api-key