MCP HubMCP Hub
osomai

servicenow-mcp

by: osomai

MCP Server for ServiceNow

43created 01/03/2025
Visit
ServiceNow

📌Overview

Purpose: This framework enables seamless integration between Claude and ServiceNow by implementing a Model Completion Protocol (MCP) server for data retrieval and action execution through the ServiceNow API.

Overview: The ServiceNow MCP Server serves as an intermediary that allows Claude to connect and interact with ServiceNow instances, facilitating a wide range of operations such as data querying, record management, and workflow execution. It supports various authentication methods to ensure secure access.

Key Features:

  • Multiple Authentication Methods: Supports Basic, OAuth, and API Key authentication for flexible access to ServiceNow instances.

  • Comprehensive Record Management: Enables querying, creating, updating, and deleting records within ServiceNow, streamlining data operations.

  • Workflow Execution: Allows execution of ServiceNow scripts and workflows, enhancing automation capabilities.

  • Service Catalog Interaction: Provides tools to access and optimize the ServiceNow Service Catalog, improving service delivery.

  • Debugging and Communication Support: Features a debug mode for troubleshooting and supports both standard input/output and Server-Sent Events (SSE) for flexible integration options.

ServiceNow MCP Server

A Model Completion Protocol (MCP) server implementation for ServiceNow, enabling Claude to interact with ServiceNow instances and perform actions through the ServiceNow API.

Overview

This project implements an MCP server that allows Claude to connect to ServiceNow, retrieve data, and perform operations. It acts as a bridge for seamless integration between Claude and ServiceNow.

Features

  • Connect using Basic, OAuth, or API Key authentication
  • Query, create, update, and delete ServiceNow records
  • Execute ServiceNow scripts and workflows
  • Access and query the ServiceNow Service Catalog
  • Analyze and optimize the Service Catalog
  • Debug mode for troubleshooting
  • Support for stdio and Server-Sent Events (SSE) communication

Installation

Prerequisites

  • Python 3.11 or higher
  • Access credentials for a ServiceNow instance

Setup

  1. Clone the repository:

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

  2. Create a virtual environment and install:

    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

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

Run as a web server using SSE for flexible integration.

Starting the SSE Server

Use the CLI:

servicenow-mcp-sse --instance-url=https://your-instance.service-now.com --username=your-username --password=your-password

Default listen address is 0.0.0.0:8080. Customize with:

servicenow-mcp-sse --host=127.0.0.1 --port=8000

Connecting to SSE Server Endpoints

  • /sse - SSE connection endpoint
  • /messages/ - Endpoint for sending messages

SSE Server Example

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

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,
)

servicenow_mcp = ServiceNowMCP(config)
app = create_starlette_app(servicenow_mcp, debug=True)

uvicorn.run(app, host="0.0.0.0", port=8080)

Available Tools

Incident Management

  • create_incident
  • update_incident
  • add_comment
  • resolve_incident
  • list_incidents

Service Catalog

  • list_catalog_items
  • get_catalog_item
  • list_catalog_categories
  • create_catalog_category
  • update_catalog_category
  • move_catalog_items
  • create_catalog_item_variable
  • list_catalog_item_variables
  • update_catalog_item_variable

Catalog Optimization

  • get_optimization_recommendations
  • update_catalog_item

Change Management

  • create_change_request
  • update_change_request
  • list_change_requests
  • get_change_request_details
  • add_change_task
  • submit_change_for_approval
  • approve_change
  • reject_change

Workflow Management

  • list_workflows
  • get_workflow
  • create_workflow
  • update_workflow
  • delete_workflow

Script Include Management

  • list_script_includes
  • get_script_include
  • create_script_include
  • update_script_include
  • delete_script_include

Changeset Management

  • list_changesets
  • get_changeset_details
  • create_changeset
  • update_changeset
  • commit_changeset
  • publish_changeset
  • add_file_to_changeset

Knowledge Base Management

  • create_knowledge_base
  • list_knowledge_bases
  • create_category
  • create_article
  • update_article
  • publish_article
  • list_articles
  • get_article

User Management

  • create_user
  • update_user
  • get_user
  • list_users
  • create_group
  • update_group
  • add_group_members
  • remove_group_members
  • list_groups

Using the MCP CLI

Register the server with Claude using:

mcp install src/servicenow_mcp/server.py -f .env

Integration with Claude Desktop

Edit the Claude Desktop config file (macOS example path) to configure the MCP server:

{
  "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 after editing.

Example Usage with Claude

Examples of commands you can ask Claude to perform:

  • Incident Management: create, update, comment, resolve, and list incidents
  • Service Catalog: show items/categories, create/update categories and variables, reorganize catalog
  • Catalog Optimization: analyze and improve catalog items
  • Change Management: create/change requests, schedule changes, submit for approval, list changes
  • Workflow Management: manage and update workflows and activities
  • Changeset Management: list, create, update, commit, publish changesets
  • Knowledge Base: create/list bases, categories, articles; update and publish articles
  • User Management: create/update users and groups, assign roles, list users/groups

Example Scripts

The repository includes example scripts:

  • examples/catalog_optimization_example.py: Analyze and improve the Service Catalog
  • examples/change_management_demo.py: Create and manage change requests

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 docs available in the docs directory:

  • Catalog Integration
  • Catalog Optimization
  • Change Management
  • Workflow Management
  • Changeset Management

Troubleshooting

Common Change Management Tool Errors

  1. argument after ** must be a mapping, not CreateChangeRequestParams

    • Pass a dictionary, not a Pydantic model object.
    • Functions now unwrap incorrect parameters automatically.

  2. Missing required parameter 'type'

    • Include required parameters (short_description, type).

  3. Invalid value for parameter 'type'

    • Use valid values: "normal", "standard", or "emergency".

  4. Cannot find get_headers method in either auth_manager or server_config

    • Pass auth_manager and server_config in correct order.
    • Functions handle parameter swapping if needed.

Contributing

Contributions welcome! To contribute:

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit changes (git commit -m 'Add some amazing feature')
  4. Push branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

License

Licensed under the MIT License - see the LICENSE file for details.