ServiceNow MCP Server

ServiceNow MCP 服务

用于 ServiceNow 的模型补全协议（MCP）服务实现，可让 Claude 与 ServiceNow 实例交互。

概述

此项目实现了一个 MCP 服务，使 Claude 能够连接到 ServiceNow 实例、检索数据，并通过 ServiceNow API 执行操作。它充当 Claude 与 ServiceNow 之间的桥梁，实现无缝集成。

功能

• 使用多种身份验证方式（Basic、OAuth、API Key）连接到 ServiceNow 实例
• 查询 ServiceNow 记录和表
• 创建、更新和删除 ServiceNow 记录
• 执行 ServiceNow 脚本和工作流
• 访问和查询 ServiceNow 服务目录
• 分析和优化 ServiceNow 服务目录
• 用于故障排除的调试模式
• 支持 stdio 和服务器发送事件（SSE）通信

安装

先决条件

• Python 3.11 或更高版本
• 具有适当访问凭据的 ServiceNow 实例

设置

1. 克隆此仓库：

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

2. 创建虚拟环境并安装软件包：

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

3. 创建包含 ServiceNow 凭据的 .env 文件：

   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
   

用法

标准（stdio）模式

启动 MCP 服务：

python -m servicenow_mcp.cli

或使用环境变量：

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

服务器发送事件（SSE）模式

ServiceNow MCP 服务也可以使用服务器发送事件（SSE）作为通信方式运行 Web 服务，从而提供更灵活的集成选项。

启动 SSE 服务

你可以使用提供的 CLI 启动 SSE 服务：

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

默认情况下，服务会监听 0.0.0.0:8080。你可以自定义主机和端口：

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

连接到 SSE 服务

SSE 服务提供两个主要端点：

• /sse - SSE 连接端点
• /messages/ - 向服务发送消息的端点

示例

完整的 SSE 服务设置和运行示例，请参阅 examples/sse_server_example.py 文件。

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)

工具打包（可选）

为了管理向大模型公开的工具数量（尤其是在存在数量限制的环境中），ServiceNow MCP 服务支持加载称为“包”的工具子集。此功能通过 MCP_TOOL_PACKAGE 环境变量控制。

配置

1. 环境变量： 将 MCP_TOOL_PACKAGE 环境变量设置为所需包的名称。

   export MCP_TOOL_PACKAGE=catalog_builder
   

2. 包定义： 可用的包及其包含的工具定义在 config/tool_packages.yaml 中。你可以自定义此文件以创建自己的包。

行为

• 如果 MCP_TOOL_PACKAGE 设置为 config/tool_packages.yaml 中定义的有效包名称，则只会加载该包中列出的工具。
• 如果未设置 MCP_TOOL_PACKAGE 或其值为空，则默认加载 full 包（包含所有工具）。
• 如果 MCP_TOOL_PACKAGE 设置为无效的包名称，则会加载 none 包（除 list_tool_packages 外不加载任何工具），并记录一条警告。
• 显式设置 MCP_TOOL_PACKAGE=none 时，不加载任何工具（list_tool_packages 除外）。

可用软件包（默认）

默认的 config/tool_packages.yaml 包含以下基于角色的软件包：

• service_desk：用于事件处理以及基本用户／知识查询的工具。
• catalog_builder：用于创建和管理服务目录条目、类别、变量及相关脚本（UI 策略、用户条件）的工具。
• change_coordinator：用于管理变更请求生命周期（包括任务和审批）的工具。
• knowledge_author：用于创建和管理知识库、类别和文章的工具。
• platform_developer：用于服务器端脚本（脚本包含）、工作流开发和部署（变更集）的工具。
• system_administrator：用于用户／群组管理和查看系统日志的工具。
• agile_management：用于管理用户故事、史诗、Scrum 任务和项目的工具。
• full：包含所有可用工具（默认）。
• none：不包含任何工具（list_tool_packages 除外）。

内省工具

• list_tool_packages：列出配置中定义的所有可用工具软件包名称，并显示当前加载的软件包。除 none 外，所有软件包均提供此工具。

可用工具

**注意：**以下工具是否可用取决于已加载的工具软件包（请参阅上方的“工具打包”部分）。默认情况下（full 软件包），所有工具均可用。

事件管理工具

1. create_incident - 在 ServiceNow 中创建新事件
2. update_incident - 更新 ServiceNow 中的现有事件
3. add_comment - 为 ServiceNow 中的事件添加评论
4. resolve_incident - 解决 ServiceNow 中的事件
5. list_incidents - 列出 ServiceNow 中的事件

服务目录工具

1. list_catalog_items - 列出 ServiceNow 中的服务目录条目
2. get_catalog_item - 获取 ServiceNow 中的指定服务目录条目
3. list_catalog_categories - 列出 ServiceNow 中的服务目录类别
4. create_catalog_category - 在 ServiceNow 中创建新的服务目录类别
5. update_catalog_category - 更新 ServiceNow 中的现有服务目录类别
6. move_catalog_items - 在 ServiceNow 中的类别之间移动目录条目
7. create_catalog_item_variable - 为目录条目创建新的变量（表单字段）
8. list_catalog_item_variables - 列出目录条目的所有变量
9. update_catalog_item_variable - 更新目录条目的现有变量
10. list_catalogs - 列出 ServiceNow 中的服务目录

目录优化工具

1. get_optimization_recommendations - 获取优化服务目录的建议
2. update_catalog_item - 更新服务目录条目

变更管理工具

1. create_change_request - 在 ServiceNow 中创建新的变更请求
2. update_change_request - 更新现有变更请求
3. list_change_requests - 列出变更请求并提供筛选选项
4. get_change_request_details - 获取指定变更请求的详细信息
5. add_change_task - 为变更请求添加任务
6. submit_change_for_approval - 提交变更请求以供审批
7. approve_change - 批准变更请求
8. reject_change - 拒绝变更请求

敏捷管理工具

故事管理

1. create_story - 在 ServiceNow 中创建新的用户故事
2. update_story - 更新 ServiceNow 中的现有用户故事
3. list_stories - 列出用户故事并提供筛选选项
4. create_story_dependency - 在两个故事之间创建依赖关系
5. delete_story_dependency - 删除故事之间的依赖关系

史诗管理

1. create_epic - 在 ServiceNow 中创建新的史诗
2. update_epic - 更新 ServiceNow 中的现有史诗
3. list_epics - 列出 ServiceNow 中的史诗并提供筛选选项

Scrum 任务管理

1. create_scrum_task - 在 ServiceNow 中创建新的 Scrum 任务
2. update_scrum_task - 更新 ServiceNow 中现有的 Scrum 任务
3. list_scrum_tasks - 列出 ServiceNow 中的 Scrum 任务，并提供筛选选项

项目管理

1. create_project - 在 ServiceNow 中创建新项目
2. update_project - 更新 ServiceNow 中现有的项目
3. list_projects - 列出 ServiceNow 中的项目，并提供筛选选项

工作流管理工具

1. list_workflows - 列出 ServiceNow 中的工作流
2. get_workflow - 获取 ServiceNow 中的特定工作流
3. create_workflow - 在 ServiceNow 中创建新的工作流
4. update_workflow - 更新 ServiceNow 中现有的工作流
5. delete_workflow - 删除 ServiceNow 中的工作流

脚本包含项管理工具

1. list_script_includes - 列出 ServiceNow 中的脚本包含项
2. get_script_include - 获取 ServiceNow 中的特定脚本包含项
3. create_script_include - 在 ServiceNow 中创建新的脚本包含项
4. update_script_include - 更新 ServiceNow 中现有的脚本包含项
5. delete_script_include - 删除 ServiceNow 中的脚本包含项

变更集管理工具

1. list_changesets - 列出 ServiceNow 中的变更集，并提供筛选选项
2. get_changeset_details - 获取特定变更集的详细信息
3. create_changeset - 在 ServiceNow 中创建新的变更集
4. update_changeset - 更新现有变更集
5. commit_changeset - 提交变更集
6. publish_changeset - 发布变更集
7. add_file_to_changeset - 将文件添加到变更集

知识库管理工具

1. create_knowledge_base - 在 ServiceNow 中创建新的知识库
2. list_knowledge_bases - 列出知识库，并提供筛选选项
3. create_category - 在知识库中创建新类别
4. create_article - 在 ServiceNow 中创建新的知识文章
5. update_article - 更新 ServiceNow 中现有的知识文章
6. publish_article - 发布 ServiceNow 中的知识文章
7. list_articles - 列出知识文章，并提供筛选选项
8. get_article - 根据 ID 获取特定知识文章

用户管理工具

1. create_user - 在 ServiceNow 中创建新用户
2. update_user - 更新 ServiceNow 中现有的用户
3. get_user - 根据 ID、用户名或电子邮件获取特定用户
4. list_users - 列出用户，并提供筛选选项
5. create_group - 在 ServiceNow 中创建新组
6. update_group - 更新 ServiceNow 中现有的组
7. add_group_members - 在 ServiceNow 中向组添加成员
8. remove_group_members - 在 ServiceNow 中从组移除成员
9. list_groups - 列出组，并提供筛选选项

UI 策略工具

1. create_ui_policy - 创建 ServiceNow UI 策略，通常用于目录项。
2. create_ui_policy_action - 创建与 UI 策略关联的操作，以控制变量状态（可见性、必填等）。

使用 MCP CLI

可以使用 MCP CLI 安装 ServiceNow MCP 服务，该工具提供了一种便捷方式，可将该服务注册到 Claude。

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

此命令会将 ServiceNow MCP 服务注册到 Claude，并配置其使用 .env 文件中的环境变量。

与 Claude Desktop 集成

要在 Claude Desktop 中配置 ServiceNow MCP 服务：

1. 编辑 Claude Desktop 配置文件，路径为 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS），或适用于你操作系统的相应路径：

{
  "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. 重启 Claude Desktop 以应用更改

使用 Claude 的示例

以下是一些自然语言查询示例，你可以使用它们通过 MCP 服务与 ServiceNow 交互：

事件管理示例

• “为东部区域的网络中断创建新事件”
• “将事件 INC0010001 的优先级更新为高”
• “为事件 INC0010001 添加评论，说明问题正在调查中”
• “解决事件 INC0010001，并注明已重启服务器”
• “列出所有分配给 Network 团队的高优先级事件”
• “列出所有分配给 Network 团队的有效 P1 事件。”

服务目录示例

• “显示服务目录中的所有项目”
• “列出所有服务目录类别”
• “获取笔记本电脑申请目录项目的详细信息”
• “显示 Hardware 类别中的所有目录项目”
• “在服务目录中搜索 ‘software’”
• “在服务目录中创建名为 ‘Cloud Services’ 的新类别”
• “将 ‘Hardware’ 类别重命名为 ‘IT Equipment’”
• “将 ‘Virtual Machine’ 目录项目移至 ‘Cloud Services’ 类别”
• “在 ‘IT Equipment’ 类别下创建名为 ‘Monitors’ 的子类别”
• “通过将所有软件项目移至 ‘Software’ 类别来重新整理我们的目录”
• “为笔记本电脑申请目录项目创建一个描述字段”
• “为目录项目添加一个用于选择笔记本电脑型号的下拉字段”
• “列出 VPN 访问申请目录项目的所有表单字段”
• “将软件申请表单中的部门字段设为必填”
• “更新成本中心字段的帮助文本”
• “显示系统中的所有服务目录”
• “列出所有硬件目录项目。”
• “查找 ‘New Laptop Request’ 的目录项目。”
• “显示 ‘New Laptop Request’ 项目的变量。”
• “为 ‘New Hire Setup’ 目录项目创建名为 ‘department_code’ 的新变量。将其设为必填字符串字段。”

目录优化示例

• “分析我们的服务目录并找出改进机会”
• “查找描述不完善、需要改进的目录项目”
• “找出使用率较低、可能需要停用的目录项目”
• “查找放弃率较高的目录项目”
• “优化我们的 Hardware 类别，改善用户体验”

变更管理示例

• “为服务器维护创建一项变更请求，以便明晚应用安全补丁”
• “安排在下周二凌晨 2 点至 4 点升级数据库”
• “为服务器维护变更添加一项实施前检查任务”
• “提交服务器维护变更以供审批”
• “批准数据库升级变更，并评论：实施计划看起来很周全”
• “显示本周安排的所有紧急变更”
• “列出所有分配给 Network 团队的变更”
• “创建一项普通变更请求，以升级生产数据库服务器。”
• “更新变更 CHG0012345，将状态设为 ‘Implement’。”

敏捷管理示例

• “创建一个新的用户故事，以实现新的报表仪表板”
• “将 ‘Implement a new reporting dashboard’ 故事更新为受阻状态”
• “列出所有分配给 Data Analytics 团队的用户故事”
• “在 ‘Implement a new reporting dashboard’ 故事和 ‘Develop data extraction pipeline’ 故事之间创建依赖关系”
• “删除 ‘Implement a new reporting dashboard’ 故事和 ‘Develop data extraction pipeline’ 故事之间的依赖关系”
• “创建一个名为 ‘Data Analytics Initiatives’ 的新史诗”
• “将 ‘Data Analytics Initiatives’ 史诗更新为已完成”
• “列出 ‘Data Analytics’ 项目中的所有史诗”
• “为 ‘Implement a new reporting dashboard’ 故事创建一个新的 Scrum 任务”
• “将 ‘Develop data extraction pipeline’ Scrum 任务更新为已完成”
• “列出 ‘Implement a new reporting dashboard’ 故事中的所有 Scrum 任务”
• “创建一个名为 ‘Data Analytics Initiatives’ 的新项目”
• “将 ‘Data Analytics Initiatives’ 项目更新为已完成”
• “列出 ‘Data Analytics’ 史诗中的所有项目”

工作流管理示例

• “显示 ServiceNow 中的所有活动工作流”
• “获取有关事件审批工作流的详细信息”
• “列出变更请求工作流的所有版本”
• “显示服务目录请求工作流中的所有活动”
• “创建一个用于处理软件许可证请求的新工作流”
• “更新事件升级工作流的描述”
• “激活新员工入职工作流”
• “停用旧的密码重置工作流”
• “向软件许可证请求工作流添加一项审批活动”
• “更新事件升级工作流中的通知活动”
• “从变更请求工作流中删除不必要的活动”
• “重新排列服务目录请求工作流中的活动”

变更集管理示例

• “列出 ServiceNow 中的所有变更集”
• “显示开发人员 ‘john.doe’ 创建的所有变更集”
• “获取有关变更集 ‘sys_update_set_123’ 的详细信息”
• “为 ‘HR Portal’ 应用创建一个新的变更集”
• “更新变更集 ‘sys_update_set_123’ 的描述”
• “使用消息 ‘Fixed login issue’ 提交变更集 ‘sys_update_set_123’”
• “将变更集 ‘sys_update_set_123’ 发布到生产环境”
• “向变更集 ‘sys_update_set_123’ 添加文件”
• “显示变更集 ‘sys_update_set_123’ 中的所有变更”

知识库示例

• “为 IT 部门创建一个新的知识库”
• “列出组织中的所有知识库”
• “在 IT 知识库中创建一个名为 ‘Network Troubleshooting’ 的类别”
• “在 ‘Network Troubleshooting’ 类别中撰写一篇关于 VPN 设置的文章”
• “更新 VPN 设置文章，添加移动设备说明”
• “发布 VPN 设置文章，使其对所有用户可见”
• “列出 ‘Network Troubleshooting’ 类别中的所有文章”
• “显示 VPN 设置文章的详细信息”
• “在 IT 知识库中查找包含 ‘password reset’ 的知识文章”
• “在 ‘Network Troubleshooting’ 类别下创建一个名为 ‘Wireless Networks’ 的子类别”

用户管理示例

• “在 Radiology 部门创建一名新用户 Dr. Alice Radiology”
• “更新 Bob 的用户记录，将他设为 Alice 的经理”
• “为 Bob 分配 ITIL 角色，使他能够审批变更请求”
• “列出 Radiology 部门中的所有用户”
• “创建一个名为 ‘Biomedical Engineering’ 的新组，用于管理医疗设备”
• “将一名管理员用户作为成员添加到 ‘Biomedical Engineering’ 组”
• “更新 ‘Biomedical Engineering’ 组以更换其经理”
• “从 ‘Biomedical Engineering’ 组中移除一名用户”
• “查找系统中职位名称包含 ‘doctor’ 的所有活动用户”
• “创建一名将担任 Radiology 部门审批人的用户”
• “列出系统中的所有 IT 支持组”

UI 策略示例

• “为 ‘Software Request’ 项目（sys_id: abc...）创建一个名为 ‘Show Justification’ 的 UI 策略，并在 ‘software_cost’ 大于 100 时应用。”
• “对于 UI 策略 ‘Show Justification’（sys_id: def...），添加一项操作，使 ‘business_justification’ 变量可见且必填。”
• “为策略 ‘Show Justification’ 创建另一项操作，以隐藏 ‘alternative_software’ 变量。”

示例脚本

此代码库包含演示如何使用这些工具的示例脚本：

• examples/catalog_optimization_example.py：演示如何分析和改进 ServiceNow 服务目录
• examples/change_management_demo.py：展示如何在 ServiceNow 中创建和管理变更请求

身份验证方式

基本身份验证

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

OAuth 身份验证

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 密钥身份验证

SERVICENOW_AUTH_TYPE=api_key
SERVICENOW_API_KEY=your-api-key

开发

文档

docs 目录中提供了其他文档：

• 目录集成 - 服务目录集成的详细信息
• 目录优化 - 目录优化功能的详细计划
• 变更管理 - 变更管理工具的详细信息
• 工作流管理 - 工作流管理工具的详细信息
• 变更集管理 - 变更集管理工具的详细信息

故障排除

变更管理工具的常见错误

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

   • 当向 create_change_request 函数传递 CreateChangeRequestParams 对象而不是字典时，会发生此错误。
   • 解决方法：确保传递的是包含参数的字典，而不是 Pydantic 模型对象。
   • 注意：变更管理工具已更新，现在可以自动处理此错误。如果参数被错误包装，或以 Pydantic 模型对象的形式传递，函数现在会尝试解包参数。

2. 错误：Missing required parameter 'type'

   • 未提供创建变更请求所需的所有参数时，会发生此错误。
   • 解决方法：确保包含所有必需参数。对于 create_change_request，short_description 和 type 均为必需参数。

3. 错误：Invalid value for parameter 'type'

   • 为 type 参数提供了无效值时，会发生此错误。
   • 解决方法：使用以下有效值之一：“normal”、“standard”或“emergency”。

4. 错误：Cannot find get_headers method in either auth_manager or server_config

   • 参数传递顺序错误，或使用的对象不具备所需方法时，会发生此错误。
   • 解决方法：确保按正确顺序传递 auth_manager 和 server_config 参数。函数已更新，现在可以自动处理参数顺序交换。

贡献

欢迎贡献！欢迎提交 Pull Request。

1. Fork 此代码库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add some amazing feature'）
4. 推送到分支（git push origin feature/amazing-feature）
5. 创建 Pull Request

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。