ServiceNow ITSM MCP server for AI agents

The ServiceNow MCP server acts as a bridge between Claude and ServiceNow instances, allowing Claude to retrieve data and perform actions in ServiceNow through the Model Completion Protocol (MCP). It enables seamless integration with ServiceNow for tasks ranging from incident management to catalog optimization.

Installation

Prerequisites

Python 3.11 or higher
A ServiceNow instance with appropriate access credentials

Setup

Clone the repository and navigate to it:

git clone https://github.com/echelon-ai-labs/servicenow-mcp.git
cd servicenow-mcp

Create a virtual environment and install the package:

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

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 Options

Standard Mode (stdio)

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

Server-Sent Events (SSE) Mode

The ServiceNow MCP server can also run as a web server using Server-Sent Events for communication.

Starting the SSE Server

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

Tool Packaging

The server supports loading subsets of tools called "packages" controlled via the MCP_TOOL_PACKAGE environment variable.

Available Packages

service_desk: Tools for incident handling and basic user/knowledge lookup
catalog_builder: Tools for managing service catalog items, categories, and variables
change_coordinator: Tools for managing change requests, including tasks and approvals
knowledge_author: Tools for managing knowledge bases, categories, and articles
platform_developer: Tools for server-side scripting and workflow development
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)

Setting a Package

export MCP_TOOL_PACKAGE=catalog_builder

Authentication Methods

Basic Authentication

SERVICENOW_AUTH_TYPE=basic
SERVICENOW_USERNAME=your-username
SERVICENOW_PASSWORD=your-password

OAuth Authentication

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

API Key Authentication

SERVICENOW_AUTH_TYPE=api_key
SERVICENOW_API_KEY=your-api-key

Integration with Claude Desktop

To configure the ServiceNow MCP server in Claude Desktop:

Edit the Claude Desktop configuration file:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "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"
      }
    }
  }
}

Restart Claude Desktop to apply the changes

Using with the MCP CLI

# Install the ServiceNow MCP server with environment variables from .env file
mcp install src/servicenow_mcp/server.py -f .env

Example Queries for Claude

Incident Management

"Create a new incident for a network outage in the east region"
"Update the priority of incident INC0010001 to high"
"List all active P1 incidents assigned to the Network team"

Service Catalog Management

"Show me all items in the service catalog"
"List all service catalog categories"
"Create a new category called 'Cloud Services' in the service catalog"
"Create a description field for the laptop request catalog item"

Change Management

"Create a change request for server maintenance to apply security patches tomorrow night"
"Submit the server maintenance change for approval"
"Show me all emergency changes scheduled for this week"

Knowledge Base Management

"Create a new knowledge base for the IT department"
"Write an article about VPN setup in the Network Troubleshooting category"
"List all articles in the Network Troubleshooting category"

User Management

"Create a new user Dr. Alice Radiology in the Radiology department"
"Assign the ITIL role to Bob so he can approve change requests"
"Create a new group called 'Biomedical Engineering' for managing medical devices"

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "ServiceNow" '{"command":"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"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "ServiceNow": {
            "command": "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"
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "ServiceNow": {
            "command": "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"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect