MseeP.ai Security Assessment Badge

ServiceNow MCP Server

A Model Completion Protocol (MCP) server implementation for ServiceNow, allowing Claude to interact with ServiceNow instances.

Deploy

Use the following button to clone the repository and directly deploy the server to Alpic:

Deploy on Alpic

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.

The server supports multiple transport modes:

• Streamable HTTP (default, Alpic-compatible) - stateless HTTP transport for cloud deployment
• Server-Sent Events (SSE) - via Starlette/Uvicorn for web-based integrations
• stdio - for local Claude Desktop integration

Features

• Implements MCP protocol revision 2026-07-28 (stateless core, server/discover, cacheable tool listings) while still serving older clients on the same endpoint
• Connect to ServiceNow instances using various authentication methods (Basic, OAuth, API Key)
• Query ServiceNow records and tables
• Create, update, and delete ServiceNow records
• Manage workflows and script includes
• Access, query, analyze, and optimize the ServiceNow Service Catalog
• Comprehensive asset management (create, update, transfer, delete assets)
• Agile management: stories, epics, scrum tasks, and projects
• Generic CRUD against any table, including custom (u_*) and scoped (x_*) tables
• Selectable tool packages to keep the advertised tool list small for model tool-selection
• Debug mode for troubleshooting
• Streamable HTTP and stdio transports (plus deprecated SSE for legacy clients)

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

Streamable HTTP Mode (Alpic-Compatible)

The recommended mode for cloud deployment and Alpic. The server runs as an HTTP endpoint with Streamable HTTP transport.

Starting the HTTP Server

# Using uv (recommended)
uv run main.py

# Or with explicit environment variables
SERVICENOW_INSTANCE_URL=https://your-instance.service-now.com \
SERVICENOW_USERNAME=your-username \
SERVICENOW_PASSWORD=your-password \
SERVICENOW_AUTH_TYPE=basic \
uv run main.py

By default, the server listens on port 3000 (set PORT env var to override).

The server exposes the MCP endpoint at:

• POST /mcp - The main MCP message endpoint for Streamable HTTP transport

Environment Variables for HTTP Mode

Variable	Required	Description
SERVICENOW_INSTANCE_URL	Yes	ServiceNow instance URL
SERVICENOW_USERNAME	Yes*	Username for basic auth
SERVICENOW_PASSWORD	Yes*	Password for basic auth
SERVICENOW_AUTH_TYPE	No	Authentication type: basic, oauth, api_key (default: basic)
SERVICENOW_CLIENT_ID	Yes**	OAuth client ID
SERVICENOW_CLIENT_SECRET	Yes**	OAuth client secret
SERVICENOW_API_KEY	Yes***	API key for api_key auth
SERVICENOW_DEBUG	No	Enable debug logging (true/false)
MCP_TOOL_PACKAGE	No	Tool package to load (default: full)
HOST	No	Address the HTTP server binds (default: 127.0.0.1; the Docker image sets 0.0.0.0)
PORT	No	HTTP server port (default: 3000)
MCP_HTTP_PATH	No	Path the MCP endpoint is served on (default: /mcp)
MCP_ALLOWED_HOSTS	No	Comma-separated Host allowlist enabling DNS-rebinding protection (e.g. mcp.example.com,mcp.example.com:443)
MCP_ALLOWED_ORIGINS	No	Comma-separated Origin allowlist, used with MCP_ALLOWED_HOSTS

Security: the MCP endpoint does not authenticate callers. Any client that can reach it can invoke tools using this server's ServiceNow credentials. HOST therefore defaults to loopback, and binding every interface is a deliberate opt-in (the Docker image sets HOST=0.0.0.0 because a container must be reachable on its published port). When you expose it, restrict access at the network boundary and set MCP_ALLOWED_HOSTS / MCP_ALLOWED_ORIGINS to turn on Host/Origin validation. The server logs a warning on startup whenever it binds a non-loopback address without an allowlist.

* Required for basic auth. ** Required for OAuth. *** Required for API key auth.

Note for Alpic Deployment: These environment variables are configured as server-side deployment settings in your Alpic project (Dashboard → Environments → Environment Variables). They are not provided by individual MCP clients connecting to your server. Each Alpic environment can point to a different ServiceNow instance, making it easy to maintain separate dev/staging/prod deployments. For shared team use, configure the credentials once per environment and share the deployment URL with your team.

MCP protocol support

This server targets MCP protocol revision 2026-07-28 (MCP Python SDK v2). That revision makes the protocol core stateless, which changes how the server deploys:

• No initialize handshake and no Mcp-Session-Id. Each request is self-contained, carrying its protocol version and client capabilities in _meta. Any instance can serve any request, so no sticky routing or shared session store is needed — a plain round-robin load balancer is enough.
• server/discover lets a client fetch supported versions, capabilities, and server identity up front, replacing the handshake.
• Header-based routing. Streamable HTTP requests carry Mcp-Method and Mcp-Name, so gateways and rate limiters can route without parsing the body. Requests whose headers disagree with the body are rejected with JSON-RPC -32020.
• Cacheable listings. tools/list and server/discover return ttlMs: 60000 and cacheScope: "public", so clients and shared intermediaries can cache them. The tool list is stable and name-sorted.

The SDK also still serves pre-2026 clients on the same endpoint, so older clients keep working without a separate deployment.

Streamable HTTP Mode (recommended)

This is the transport to use for remote/hosted deployments:

uv run main.py

It serves POST /mcp on 127.0.0.1:3000 by default; override with HOST, PORT, and MCP_HTTP_PATH. This is also what the Docker image runs, which sets HOST=0.0.0.0 so the published port is reachable — see the security note under Environment Variables before exposing it.

Standard (stdio) Mode

To start the MCP server:

python -m servicenow_mcp.cli
#or
uv run servicenow-mcp

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 — deprecated

Deprecated. HTTP+SSE has been deprecated since protocol revision 2025-03-26 and is formally in the Deprecated state under the MCP feature lifecycle policy introduced in 2026-07-28. It cannot carry the stateless core, so clients connecting here negotiate an older protocol revision. It is retained only so existing deployments keep working — use Streamable HTTP (uv run main.py) for anything new.

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)

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.

   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 at all, not even list_tool_packages), and a warning is logged.
• Setting MCP_TOOL_PACKAGE=none explicitly loads no tools at all — list_tool_packages is not exposed either, so a client cannot discover the other packages from this state.

Available Packages (Default)

The default config/tool_packages.yaml defines these role-based packages. Counts are the number of tools each one actually serves over tools/list, including list_tool_packages:

Package	Tools	Purpose
service_desk	12	Incident handling plus basic user and knowledge lookup
catalog_builder	15	Creating and managing catalog items, categories, and variables
change_coordinator	9	Change request lifecycle, tasks, and approvals
knowledge_author	10	Knowledge bases, categories, and articles
platform_developer	26	Script includes, workflow development, changesets
agile_management	23	Stories, epics, scrum tasks, and projects
system_administrator	17	User and group management
schema_manager	8	Table schema inspection
custom_tables	9	Generic CRUD against any table
get_request_tools	39	Request, catalog, and expense oriented subset
full	107	Everything except the agile suite (default)
none	0	No tools at all, including no list_tool_packages

Note that full does not include the agile tools (stories, epics, scrum tasks, projects). They are implemented and fully supported, but kept out of the default package so the default tool list stays manageable for model tool-selection. Set MCP_TOOL_PACKAGE=agile_management to use them.

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

The server implements 122 tools in total: 121 ServiceNow tools plus the list_tool_packages introspection tool. How many are advertised over tools/list depends on the loaded tool package (see Tool Packaging above) — the default full package serves 107 of them.

Tools marked :package: are not in the full package and require selecting the package named in their section heading via MCP_TOOL_PACKAGE.

Incident Management

1. add_comment - Add a comment to an incident in ServiceNow
2. create_incident - Create a new incident in ServiceNow
3. get_incident_by_number - Fetch a single incident from ServiceNow by its number
4. list_incidents - List incidents from ServiceNow
5. resolve_incident - Resolve an incident in ServiceNow
6. update_incident - Update an existing incident in ServiceNow

Service Catalog

1. create_catalog_category - Create a new service catalog category.
2. create_catalog_item - Create a new service catalog item.
3. delete_catalog_category - Delete an existing service catalog category.
4. get_catalog_item - Get a specific service catalog item.
5. list_catalog_categories - List service catalog categories.
6. list_catalog_items - List service catalog items.
7. list_catalogs - List service catalogs from ServiceNow
8. move_catalog_items - Move catalog items to a different category.
9. order_catalog_item - Order a catalog item
10. update_catalog_category - Update an existing service catalog category.

Catalog Item Variables

1. create_catalog_item_variable - Create a new catalog item variable
2. delete_catalog_item_variable - Delete a variable (form field) from a service catalog item
3. list_catalog_item_variables - List catalog item variables
4. update_catalog_item_variable - Update a catalog item variable

Catalog Optimization

1. get_optimization_recommendations - Get optimization recommendations for the service catalog.
2. update_catalog_item - Update a service catalog item.

Change Management

1. add_change_task - Add a task to a change request
2. approve_change - Approve a change request
3. create_change_request - Create a new change request in ServiceNow
4. get_change_request_details - Get detailed information about a specific change request
5. list_change_requests - List change requests from ServiceNow
6. reject_change - Reject a change request
7. submit_change_for_approval - Submit a change request for approval
8. update_change_request - Update an existing change request in ServiceNow

Agile — Story Management :package: agile_management

1. create_story :package: - Create a new story in ServiceNow
2. create_story_dependency :package: - Create a dependency between two stories in ServiceNow
3. delete_story_dependency :package: - Delete a story dependency in ServiceNow
4. list_stories :package: - List stories from ServiceNow
5. list_story_dependencies :package: - List story dependencies from ServiceNow
6. update_story :package: - Update an existing story in ServiceNow

Agile — Epic Management :package: agile_management

1. create_epic :package: - Create a new epic in ServiceNow
2. list_epics :package: - List epics from ServiceNow
3. update_epic :package: - Update an existing epic in ServiceNow

Agile — Scrum Task Management :package: agile_management

1. create_scrum_task :package: - Create a new scrum task in ServiceNow
2. list_scrum_tasks :package: - List scrum tasks from ServiceNow
3. update_scrum_task :package: - Update an existing scrum task in ServiceNow

Agile — Project Management :package: agile_management

1. create_project :package: - Create a new project in ServiceNow
2. list_projects :package: - List projects from ServiceNow
3. update_project :package: - Update an existing project in ServiceNow

Asset Management

1. create_asset - Create a new asset in ServiceNow
2. create_currency_instance - Create a new currency instance in ServiceNow
3. create_hardware_asset - Create a new hardware asset in ServiceNow
4. delete_asset - Delete an asset from ServiceNow
5. get_assets - Get, list, or search for assets in ServiceNow. Supports single asset lookup by ID/tag/serial, filtering by user/location, and searching by name or general query.
6. list_hardware_assets - List hardware assets from ServiceNow
7. transfer_asset - Transfer an asset to a different user in ServiceNow
8. update_asset - Update an existing asset in ServiceNow
9. update_hardware_asset - Update an existing hardware asset in ServiceNow

Problem Management

1. create_problem - Create a new problem in ServiceNow

Custom / Generic Table

1. create_table_record - DYNAMIC: create a record in any table_name passed at runtime.
2. delete_table_record - DYNAMIC: delete a record from any table_name passed at runtime.
3. get_table_record - DYNAMIC: get one record by sys_id from any table_name passed at runtime.
4. list_custom_tables - Discover custom/scoped tables dynamically (x_* and u_*) from sys_db_object. Pass any returned name into the CRUD tools.
5. list_table_records - DYNAMIC: list/query records from any table by passing table_name at runtime (any x_* scoped, u_* custom, or OOB table).
6. update_table_record - DYNAMIC: update a record in any table_name passed at runtime.

Workflow Management

1. activate_workflow - Activate a workflow in ServiceNow
2. add_workflow_activity - Add a new activity to a workflow in ServiceNow
3. create_workflow - Create a new workflow in ServiceNow
4. deactivate_workflow - Deactivate a workflow in ServiceNow
5. delete_workflow - Delete a workflow
6. delete_workflow_activity - Delete an activity from a workflow
7. get_workflow_activities - Get activities for a specific workflow
8. get_workflow_details - Get detailed information about a specific workflow
9. list_workflow_versions - List workflow versions from ServiceNow
10. list_workflows - List workflows from ServiceNow
11. reorder_workflow_activities - Reorder activities in a workflow
12. update_workflow - Update an existing workflow in ServiceNow
13. update_workflow_activity - Update an existing activity in a workflow

Script Include Management

1. create_script_include - Create a new script include in ServiceNow
2. delete_script_include - Delete a script include in ServiceNow
3. get_script_include - Get a specific script include from ServiceNow
4. list_script_includes - List script includes from ServiceNow
5. update_script_include - Update an existing script include in ServiceNow

Changeset Management

1. add_file_to_changeset - Add a file to a changeset in ServiceNow
2. commit_changeset - Commit a changeset in ServiceNow
3. create_changeset - Create a new changeset in ServiceNow
4. get_changeset_details - Get detailed information about a specific changeset
5. list_changesets - List changesets from ServiceNow
6. publish_changeset - Publish a changeset in ServiceNow
7. update_changeset - Update an existing changeset in ServiceNow

Knowledge Base Management

1. create_article - Create a new knowledge article
2. create_category - Create a new category in a knowledge base
3. create_knowledge_base - Create a new knowledge base in ServiceNow
4. get_article - Get a specific knowledge article by ID
5. list_articles - List knowledge articles
6. list_categories - List categories in a knowledge base
7. list_knowledge_bases - List knowledge bases from ServiceNow
8. publish_article - Publish a knowledge article
9. update_article - Update an existing knowledge article

User & Group Management

1. add_group_members - Add members to an existing group in ServiceNow
2. create_group - Create a new group in ServiceNow
3. create_user - Create a new user in ServiceNow
4. get_user - Get a specific user in ServiceNow
5. list_group_members - List members of an existing group in ServiceNow
6. list_groups - List groups from ServiceNow with optional filtering
7. list_groups_clearance - List clearance level for groups in ServiceNow
8. list_users - List users in ServiceNow
9. list_users_clearance - List clearance level for users in ServiceNow
10. remove_group_members - Remove members from an existing group in ServiceNow
11. update_group - Update an existing group in ServiceNow
12. update_group_clearance - Update clearance level for a group in ServiceNow
13. update_user - Update an existing user in ServiceNow
14. update_user_clearance - Update clearance level for a user in ServiceNow

Request Management

1. change_request_item_priority - Change the priority of a change request item
2. create_item_request - Create a new item request in ServiceNow. This is used to create a request for a specific item. You can link multiple item requests to a single request object.
3. list_item_requests - List item requests from ServiceNow

Expense Management

1. delete_expense_line - Delete an expense line from ServiceNow
2. list_expense_lines - List expense lines from ServiceNow. These hold the details of all the expenses that are made.

Report & Dashboard

1. get_canvas - Get the canvas page id linked to the dashboard tab.
2. get_dashboard_tab - Get the dashboard tab id linked to the dashboard.
3. get_portal_widgets - Get all the portal widget ids linked to the canvas page.
4. get_report - Get a specific report from ServiceNow. All the ServiceNow charts are represented as reports.
5. get_report_ids_from_portal_widgets - Get all the report ids linked to the portal widgets on a dashboard.
6. search_any_table - Search any ServiceNow table.

Schema Management

1. get_table_schema - Get the schema of a ServiceNow table.

Introspection

1. list_tool_packages - Lists available tool packages and the currently loaded one

Known gaps

These tool names appear commented out in config/tool_packages.yaml and are not implemented. They are kept as comments to record the intent rather than silently advertising tools that do not exist:

• create_ui_policy, create_ui_policy_action — catalog UI policy management
• create_user_criteria, create_user_criteria_condition — catalog user criteria
• create_catalog_variable_choice — choice options for a catalog variable
• execute_script_include — requires a scripted REST endpoint (see SCRIPT_EXECUTION_API_RESOURCE_PATH)
• list_syslog_entries, get_syslog_entry — system log access

get_asset, list_assets, and search_assets_by_name were consolidated into the single get_assets tool, which covers single-asset lookup, filtering, and name search.

The server also does not expose MCP resources (resources/list / resources/read) — only tools. Skipped specs for a resources layer live in tests/test_*_resources.py.

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

2. Restart Claude Desktop to apply the changes

Example Usage with Claude

Below are some example natural language queries you can use with Claude to interact with ServiceNow via the MCP server:

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"
• "List all active P1 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"
• "Show me all service catalogs in the system"
• "List all hardware catalog items."
• "Find the catalog item for 'New Laptop Request'."
• "Show me the variables for the 'New Laptop Request' item."
• "Create a new variable named 'department_code' for the 'New Hire Setup' catalog item. Make it a mandatory string 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"
• "Create a normal change request to upgrade the production database server."
• "Update change CHG0012345, set the state to 'Implement'."

Agile Management Examples

Requires MCP_TOOL_PACKAGE=agile_management; these tools are not in the default full package.

• "Create a new user story for implementing a new reporting dashboard"
• "Update the 'Implement a new reporting dashboard' story to set it as blocked"
• "List all user stories assigned to the Data Analytics team"
• "Create a dependency between the 'Implement a new reporting dashboard' story and the 'Develop data extraction pipeline' story"
• "Delete the dependency between the 'Implement a new reporting dashboard' story and the 'Develop data extraction pipeline' story"
• "Create a new epic called 'Data Analytics Initiatives'"
• "Update the 'Data Analytics Initiatives' epic to set it as completed"
• "List all epics in the 'Data Analytics' project"
• "Create a new scrum task for the 'Implement a new reporting dashboard' story"
• "Update the 'Develop data extraction pipeline' scrum task to set it as completed"
• "List all scrum tasks in the 'Implement a new reporting dashboard' story"
• "Create a new project called 'Data Analytics Initiatives'"
• "Update the 'Data Analytics Initiatives' project to set it as completed"
• "List all projects in the 'Data Analytics' epic"

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"

Custom Table Examples

• "List custom and scoped tables on this instance"
• "Find scoped tables whose name contains demand"
• "Get the schema for the custom table x_imev_service_cen_demand"
• "List one record from x_imev_service_cen_demand"
• "Query any scoped table I name by passing table_name at runtime"
• "Create a record in x_imev_service_cen_demand with short_description 'New demand'"
• "Update record abc123 in x_imev_service_cen_demand and set state to 2"
• "Delete record abc123 from x_imev_service_cen_demand"

Example Scripts

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

• examples/asset_management_demo.py: Comprehensive demonstration of asset management features
• 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:

• Asset Management - Comprehensive guide to asset management features
• 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

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.