Skip to main content
Glama

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.

Related MCP server: ServiceNow MCP Server

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

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:

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

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.

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

# Create server configuration
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,
)

# Create ServiceNow MCP server
servicenow_mcp = ServiceNowMCP(config)

# Create Starlette app with SSE transport
app = create_starlette_app(servicenow_mcp, debug=True)

# Start the web server
uvicorn.run(app, host="0.0.0.0", port=8080)

Available Tools

The ServiceNow MCP server provides the following tools:

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

  4. resolve_incident - Resolve an incident in ServiceNow

  5. list_incidents - List incidents from ServiceNow

Service Catalog Tools

  1. list_catalog_items - List service catalog items from ServiceNow

  2. get_catalog_item - Get a specific service catalog item from ServiceNow

  3. list_catalog_categories - List service catalog categories from ServiceNow

  4. create_catalog_category - Create a new service catalog category in ServiceNow

  5. update_catalog_category - Update an existing service catalog category in ServiceNow

  6. move_catalog_items - Move catalog items between categories in ServiceNow

  7. create_catalog_item_variable - Create a new variable (form field) for a catalog item

  8. list_catalog_item_variables - List all variables for a catalog item

  9. update_catalog_item_variable - Update an existing variable for a catalog item

Catalog Optimization Tools

  1. get_optimization_recommendations - Get recommendations for optimizing the service catalog

  2. update_catalog_item - Update a service catalog item

Change Management Tools

  1. create_change_request - Create a new change request in ServiceNow

  2. update_change_request - Update an existing change request

  3. list_change_requests - List change requests with filtering options

  4. get_change_request_details - Get detailed information about a specific change request

  5. add_change_task - Add a task to a change request

  6. submit_change_for_approval - Submit a change request for approval

  7. approve_change - Approve a change request

  8. reject_change - Reject a change request

Workflow Management Tools

  1. list_workflows - List workflows from ServiceNow

  2. get_workflow - Get a specific workflow from ServiceNow

  3. create_workflow - Create a new workflow in ServiceNow

  4. update_workflow - Update an existing workflow in ServiceNow

  5. delete_workflow - Delete a workflow from ServiceNow

Script Include Management Tools

  1. list_script_includes - List script includes from ServiceNow

  2. get_script_include - Get a specific script include from ServiceNow

  3. create_script_include - Create a new script include in ServiceNow

  4. update_script_include - Update an existing script include in ServiceNow

  5. delete_script_include - Delete a script include from ServiceNow

Changeset Management Tools

  1. list_changesets - List changesets from ServiceNow with filtering options

  2. get_changeset_details - Get detailed information about a specific changeset

  3. create_changeset - Create a new changeset in ServiceNow

  4. update_changeset - Update an existing changeset

  5. commit_changeset - Commit a changeset

  6. publish_changeset - Publish a changeset

  7. add_file_to_changeset - Add a file to a changeset

Knowledge Base Management Tools

  1. create_knowledge_base - Create a new knowledge base in ServiceNow

  2. list_knowledge_bases - List knowledge bases with filtering options

  3. create_category - Create a new category in a knowledge base

  4. create_article - Create a new knowledge article in ServiceNow

  5. update_article - Update an existing knowledge article in ServiceNow

  6. publish_article - Publish a knowledge article in ServiceNow

  7. list_articles - List knowledge articles with filtering options

  8. get_article - Get a specific knowledge article by ID

User Management Tools

  1. create_user - Create a new user in ServiceNow

  2. update_user - Update an existing user in ServiceNow

  3. get_user - Get a specific user by ID, username, or email

  4. list_users - List users with filtering options

  5. create_group - Create a new group in ServiceNow

  6. update_group - Update an existing group in ServiceNow

  7. add_group_members - Add members to a group in ServiceNow

  8. remove_group_members - Remove members from a group in ServiceNow

  9. list_groups - List groups with filtering options

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:

  1. 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"
      }
    }
  }
}
  1. 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"

  • "Create a description field for the laptop request catalog item"

  • "Add a dropdown field for selecting laptop models to catalog item"

  • "List all form fields for the VPN access request catalog item"

  • "Make the department field mandatory in the software request form"

  • "Update the help text for the cost center field"

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

Knowledge Base Examples

  • "Create a new knowledge base for the IT department"

  • "List all knowledge bases in the organization"

  • "Create a category called 'Network Troubleshooting' in the IT knowledge base"

  • "Write an article about VPN setup in the Network Troubleshooting category"

  • "Update the VPN setup article to include mobile device instructions"

  • "Publish the VPN setup article so it's visible to all users"

  • "List all articles in the Network Troubleshooting category"

  • "Show me the details of the VPN setup article"

  • "Find knowledge articles containing 'password reset' in the IT knowledge base"

  • "Create a subcategory called 'Wireless Networks' under the Network Troubleshooting category"

User Management Examples

  • "Create a new user Dr. Alice Radiology in the Radiology department"

  • "Update Bob's user record to make him the manager of Alice"

  • "Assign the ITIL role to Bob so he can approve change requests"

  • "List all users in the Radiology department"

  • "Create a new group called 'Biomedical Engineering' for managing medical devices"

  • "Add an admin user to the Biomedical Engineering group as a member"

  • "Update the Biomedical Engineering group to change its manager"

  • "Remove a user from the Biomedical Engineering group"

  • "Find all active users in the system with 'doctor' in their title"

  • "Create a user that will act as an approver for the Radiology department"

  • "List all IT support groups in the system"

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:

Troubleshooting

Common Errors with Change Management Tools

  1. 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.

  2. 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.

  3. 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.

  1. Fork the repository

  2. Create your feature branch (git checkout -b feature/amazing-feature)

  3. Commit your changes (git commit -m 'Add some amazing feature')

  4. Push to the branch (git push origin feature/amazing-feature)

  5. Open a Pull Request

License

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

Available Tools

66 tools
activate_workflowC

Activate a workflow in ServiceNow

Inputs: params (required).

add_change_taskC

Add a task to a change request

Inputs: params (required).

add_commentB

Add a comment to an incident in ServiceNow

Inputs: params (required).

add_file_to_changesetC

Add a file to a changeset in ServiceNow

Inputs: params (required).

add_group_membersC

Add members to an existing group in ServiceNow

Inputs: params (required).

add_workflow_activityC

Add a new activity to a workflow in ServiceNow

Inputs: params (required).

approve_changeC

Approve a change request

Inputs: params (required).

commit_changesetC

Commit a changeset in ServiceNow

Inputs: params (required).

create_articleC

Create a new knowledge article

Inputs: params (required).

create_catalog_categoryC

Create a new service catalog category.

Inputs: params (required).

create_catalog_item_variableC

Create a new catalog item variable

Inputs: params (required).

create_categoryC

Create a new category in a knowledge base

Inputs: params (required).

create_change_requestC

Create a new change request in ServiceNow

Inputs: params (required).

create_changesetC

Create a new changeset in ServiceNow

Inputs: params (required).

create_groupC

Create a new group in ServiceNow

Inputs: params (required).

create_incidentC

Create a new incident in ServiceNow

Inputs: params (required).

create_knowledge_baseC

Create a new knowledge base in ServiceNow

Inputs: params (required).

create_script_includeC

Create a new script include in ServiceNow

Inputs: params (required).

create_userC

Create a new user in ServiceNow

Inputs: params (required).

create_workflowC

Create a new workflow in ServiceNow

Inputs: params (required).

deactivate_workflowC

Deactivate a workflow in ServiceNow

Inputs: params (required).

delete_script_includeC

Delete a script include in ServiceNow

Inputs: params (required).

delete_workflow_activityC

Delete an activity from a workflow

Inputs: params (required).

get_articleC

Get a specific knowledge article by ID

Inputs: params (required).

get_catalog_itemC

Get a specific service catalog item.

Inputs: params (required).

get_change_request_detailsC

Get detailed information about a specific change request

Inputs: params (required).

get_changeset_detailsC

Get detailed information about a specific changeset

Inputs: params (required).

get_optimization_recommendationsC

Get optimization recommendations for the service catalog.

Inputs: params (required).

get_script_includeC

Get a specific script include from ServiceNow

Inputs: params (required).

get_userC

Get a specific user in ServiceNow

Inputs: params (required).

get_workflow_activitiesC

Get activities for a specific workflow

Inputs: params (required).

get_workflow_detailsC

Get detailed information about a specific workflow

Inputs: params (required).

list_articlesD

List knowledge articles

Inputs: params (required).

list_catalog_categoriesC

List service catalog categories.

Inputs: params (required).

list_catalog_itemsB

List service catalog items.

Inputs: params (required).

list_catalog_item_variablesD

List catalog item variables

Inputs: params (required).

list_categoriesC

List categories in a knowledge base

Inputs: params (required).

list_change_requestsC

List change requests from ServiceNow

Inputs: params (required).

list_changesetsC

List changesets from ServiceNow

Inputs: params (required).

list_groupsC

List groups from ServiceNow with optional filtering

Inputs: params (required).

list_incidentsC

List incidents from ServiceNow

Inputs: params (required).

list_knowledge_basesC

List knowledge bases from ServiceNow

Inputs: params (required).

list_script_includesC

List script includes from ServiceNow

Inputs: params (required).

list_usersC

List users in ServiceNow

Inputs: params (required).

list_workflowsC

List workflows from ServiceNow

Inputs: params (required).

list_workflow_versionsC

List workflow versions from ServiceNow

Inputs: params (required).

move_catalog_itemsC

Move catalog items to a different category.

Inputs: params (required).

publish_articleD

Publish a knowledge article

Inputs: params (required).

publish_changesetC

Publish a changeset in ServiceNow

Inputs: params (required).

reject_changeD

Reject a change request

Inputs: params (required).

remove_group_membersC

Remove members from an existing group in ServiceNow

Inputs: params (required).

reorder_workflow_activitiesC

Reorder activities in a workflow

Inputs: params (required).

resolve_incidentC

Resolve an incident in ServiceNow

Inputs: params (required).

submit_change_for_approvalC

Submit a change request for approval

Inputs: params (required).

update_articleC

Update an existing knowledge article

Inputs: params (required).

update_catalog_categoryC

Update an existing service catalog category.

Inputs: params (required).

update_catalog_itemC

Update a service catalog item.

Inputs: params (required).

update_catalog_item_variableD

Update a catalog item variable

Inputs: params (required).

update_change_requestC

Update an existing change request in ServiceNow

Inputs: params (required).

update_changesetC

Update an existing changeset in ServiceNow

Inputs: params (required).

update_groupC

Update an existing group in ServiceNow

Inputs: params (required).

update_incidentC

Update an existing incident in ServiceNow

Inputs: params (required).

update_script_includeC

Update an existing script include in ServiceNow

Inputs: params (required).

update_userC

Update an existing user in ServiceNow

Inputs: params (required).

update_workflowC

Update an existing workflow in ServiceNow

Inputs: params (required).

update_workflow_activityC

Update an existing activity in a workflow

Inputs: params (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.7/5.0

    Scored across 66 tools

    Disambiguation4/5

    Most tools have distinct purposes targeting specific ServiceNow resources and actions, with clear boundaries like create_incident vs. resolve_incident. However, some overlap exists between catalog-related tools (e.g., create_catalog_category vs. update_catalog_category) and knowledge base tools (list_articles vs. get_article), which could cause minor confusion but descriptions help differentiate them.

    Naming Consistency5/5

    Tool names follow a highly consistent verb_noun pattern throughout, such as create_incident, list_users, update_workflow, and get_change_request_details. All tools use snake_case with clear action-object naming, making them predictable and easy to understand without any deviations in convention.

    Tool Count2/5

    With 66 tools, the count is excessive for typical MCP server scopes, making it feel heavy and potentially overwhelming for agents. While ServiceNow is a broad platform, this many tools suggests poor scoping or fragmentation, as many operations could be consolidated into fewer, more general tools.

    Completeness5/5

    The tool set provides comprehensive CRUD and lifecycle coverage across multiple ServiceNow domains, including incidents, change requests, knowledge bases, workflows, and users. It includes all essential operations from creation to deletion, with no obvious gaps, ensuring agents can handle full workflows without dead ends.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      Not graded
      maintenance
      Enables Claude to interact with ServiceNow instances through the ServiceNow API. Supports comprehensive ServiceNow operations including incident management, service catalog management, change requests, user management, and workflow automation through natural language.
      82
      MIT
    • A
      license
      C
      quality
      D
      maintenance
      Enables Claude to interact with ServiceNow instances through comprehensive API integration. Supports incident management, service catalog operations, change requests, knowledge base management, user administration, and agile project management with multiple authentication methods.
      82
      MIT
    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables Claude to interact with ServiceNow instances for incident management, service catalog operations, change requests, knowledge base management, user administration, and agile project workflows through various authentication methods.
      MIT