ServiceNow MCP Server

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

Installation

Prerequisites

Python 3.11 or higher
A ServiceNow instance with appropriate access credentials

Setup

Clone this repository:

git clone https://github.com/yourusername/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

Running the Server

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

Available Tools

The ServiceNow MCP server provides the following tools:

Incident Management Tools

create_incident - Create a new incident in ServiceNow

         2. **update_incident** - Update an existing incident in ServiceNow

add_comment - Add a comment to an incident in ServiceNow
resolve_incident - Resolve an incident in ServiceNow
list_incidents - List incidents from ServiceNow

Service Catalog Tools

list_catalog_items - List service catalog items from ServiceNow
get_catalog_item - Get a specific service catalog item from ServiceNow
list_catalog_categories - List service catalog categories from ServiceNow
create_catalog_category - Create a new service catalog category in ServiceNow
update_catalog_category - Update an existing service catalog category in ServiceNow
move_catalog_items - Move catalog items between categories in ServiceNow

Catalog Optimization Tools

get_optimization_recommendations - Get recommendations for optimizing the service catalog
update_catalog_item - Update a service catalog item

Change Management Tools

create_change_request - Create a new change request in ServiceNow
update_change_request - Update an existing change request
list_change_requests - List change requests with filtering options
get_change_request_details - Get detailed information about a specific change request
add_change_task - Add a task to a change request
submit_change_for_approval - Submit a change request for approval
approve_change - Approve a change request
reject_change - Reject a change request

Workflow Management Tools

list_workflows - List workflows from ServiceNow
get_workflow - Get a specific workflow from ServiceNow
create_workflow - Create a new workflow in ServiceNow
update_workflow - Update an existing workflow in ServiceNow
delete_workflow - Delete a workflow from ServiceNow

Script Include Management Tools

list_script_includes - List script includes from ServiceNow

         2. **get_script_include** - Get a specific script include from ServiceNow

create_script_include - Create a new script include in ServiceNow
update_script_include - Update an existing script include in ServiceNow
delete_script_include - Delete a script include from ServiceNow

Changeset Management Tools

list_changesets - List changesets from ServiceNow with filtering options
get_changeset_details - Get detailed information about a specific changeset
create_changeset - Create a new changeset in ServiceNow
update_changeset - Update an existing changeset
commit_changeset - Commit a changeset
publish_changeset - Publish a changeset
add_file_to_changeset - Add a file to a changeset

Using the MCP CLI

The ServiceNow MCP server can be installed with the MCP CLI, which provides a convenient way to register the server with Claude.

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

This command will register the ServiceNow MCP server with Claude and configure it to use the environment variables from the .env file.

Integration with Claude Desktop

To configure the ServiceNow MCP server in Claude Desktop:

Edit the Claude Desktop configuration file at ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the appropriate path for your OS:

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

Example Usage with Claude

            Once the ServiceNow MCP server is configured with Claude Desktop, you can ask Claude to perform actions like:

Incident Management Examples

"Create a new incident for a network outage in the east region"
"Update the priority of incident INC0010001 to high"
"Add a comment to incident INC0010001 saying the issue is being investigated"
"Resolve incident INC0010001 with a note that the server was restarted"
"List all high priority incidents assigned to the Network team"

Service Catalog Examples

"Show me all items in the service catalog"
"List all service catalog categories"
"Get details about the laptop request catalog item"
"Show me all catalog items in the Hardware category"
"Search for 'software' in the service catalog"
"Create a new category called 'Cloud Services' in the service catalog"
"Update the 'Hardware' category to rename it to 'IT Equipment'"
"Move the 'Virtual Machine' catalog item to the 'Cloud Services' category"
"Create a subcategory called 'Monitors' under the 'IT Equipment' category"
"Reorganize our catalog by moving all software items to the 'Software' category"

Catalog Optimization Examples

"Analyze our service catalog and identify opportunities for improvement"
"Find catalog items with poor descriptions that need improvement"
"Identify catalog items with low usage that we might want to retire"
"Find catalog items with high abandonment rates"
"Optimize our Hardware category to improve user experience"

Change Management Examples

"Create a change request for server maintenance to apply security patches tomorrow night"
"Schedule a database upgrade for next Tuesday from 2 AM to 4 AM"
"Add a task to the server maintenance change for pre-implementation checks"
"Submit the server maintenance change for approval"
"Approve the database upgrade change with comment: implementation plan looks thorough"

"Show me all emergency changes scheduled for this week"

          - "List all changes assigned to the Network team"

Workflow Management Examples

"Show me all active workflows in ServiceNow"
"Get details about the incident approval workflow"
"List all versions of the change request workflow"
"Show me all activities in the service catalog request workflow"
"Create a new workflow for handling software license requests"
"Update the description of the incident escalation workflow"
"Activate the new employee onboarding workflow"
"Deactivate the old password reset workflow"
"Add an approval activity to the software license request workflow"
"Update the notification activity in the incident escalation workflow"
"Delete the unnecessary activity from the change request workflow"
"Reorder the activities in the service catalog request workflow"

Changeset Management Examples

"List all changesets in ServiceNow"
"Show me all changesets created by developer 'john.doe'"
"Get details about changeset 'sys_update_set_123'"
"Create a new changeset for the 'HR Portal' application"
"Update the description of changeset 'sys_update_set_123'"
"Commit changeset 'sys_update_set_123' with message 'Fixed login issue'"
"Publish changeset 'sys_update_set_123' to production"
"Add a file to changeset 'sys_update_set_123'"
"Show me all changes in changeset 'sys_update_set_123'"

Example Scripts

The repository includes example scripts that demonstrate how to use the tools:

examples/catalog_optimization_example.py: Demonstrates how to analyze and improve the ServiceNow Service Catalog
examples/change_management_demo.py: Shows how to create and manage change requests in ServiceNow

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

Development

Documentation

Additional documentation is available in the docs directory:

Catalog Integration - Detailed information about the Service Catalog integration
Catalog Optimization - Detailed plan for catalog optimization features
Change Management - Detailed information about the Change Management tools
Workflow Management - Detailed information about the Workflow Management tools
Changeset Management - Detailed information about the Changeset Management tools

Troubleshooting

Common Errors with Change Management Tools

Error: argument after ** must be a mapping, not CreateChangeRequestParams
- This error occurs when you pass a CreateChangeRequestParams object instead of a dictionary to the create_change_request function.
- Solution: Make sure you're passing a dictionary with the parameters, not a Pydantic model object.
- Note: The change management tools have been updated to handle this error automatically. The functions will now attempt to unwrap parameters if they're incorrectly wrapped or passed as a Pydantic model object.
Error: Missing required parameter 'type'
- This error occurs when you don't provide all required parameters for creating a change request.
- Solution: Make sure to include all required parameters. For create_change_request, both short_description and type are required.
Error: Invalid value for parameter 'type'
- This error occurs when you provide an invalid value for the type parameter.
- Solution: Use one of the valid values: "normal", "standard", or "emergency".
```
       4. **Error: `Cannot find get_headers method in either auth_manager or server_config`**
```
- This error occurs when the parameters are passed in the wrong order or when using objects that don't have the required methods.
- Solution: Make sure you're passing the auth_manager and server_config parameters in the correct order. The functions have been updated to handle parameter swapping automatically.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

servicenow-mcp

Language:

Stars:

Forks: