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/yourusername/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 服务器：

或者使用环境变量：

服务器发送事件 (SSE) 模式

ServiceNow MCP 服务器还可以作为 Web 服务器运行，使用服务器发送事件 (SSE) 进行通信，从而提供更灵活的集成选项。

启动 SSE 服务器

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

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

连接到 SSE 服务器

SSE 服务器公开两个主要端点：

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

例子

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

工具包装（可选）

为了管理暴露给语言模型的工具数量（尤其是在功能受限的环境中），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 ：用于用户/组管理和查看系统日志的工具。
• 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. rejection_change - 拒绝变更请求

工作流管理工具

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

ServiceNow MCP 服务器可以使用 MCP CLI 安装，这提供了一种使用 Claude 注册服务器的便捷方法。

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

与 Claude Desktop 集成

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

1. 编辑位于~/Library/Application Support/Claude/claude_desktop_config.json (macOS) 或适合您操作系统的路径的 Claude Desktop 配置文件：

2. 重新启动 Claude Desktop 以应用更改

Claude 的示例用法

以下是一些示例自然语言查询，您可以使用 Claude 通过 MCP 服务器与 ServiceNow 进行交互：

事件管理示例

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

服务目录示例

• “显示服务目录中的所有项目”
• “列出所有服务目录类别”
• “获取有关笔记本电脑请求目录项的详细信息”
• “显示硬件类别中的所有目录项”
• “在服务目录中搜索‘软件’”
• “在服务目录中创建一个名为‘云服务’的新类别”
• “更新‘硬件’类别，将其重命名为‘IT 设备’”
• 将‘虚拟机’目录项移动到‘云服务’类别
• “在‘IT 设备’类别下创建一个名为‘显示器’的子类别”
• “通过将所有软件项目移至‘软件’类别来重新组织我们的目录”
• “为笔记本电脑请求目录项创建描述字段”
• “添加一个下拉字段，用于选择要编入目录的笔记本电脑型号”
• “列出 VPN 访问请求目录项的所有表单字段”
• “将软件请求表中的部门字段设为必填项”
• “更新成本中心字段的帮助文本”
• “显示系统中的所有服务目录”
• “列出所有硬件目录项。”
• “查找‘新笔记本电脑请求’的目录项。”
• “向我显示‘新笔记本电脑请求’项目的变量。”
• 为“新员工设置”目录项创建一个名为“department_code”的新变量。使其成为必填字符串字段。

目录优化示例

• “分析我们的服务目录并找出改进的机会”
• “查找描述不充分且需要改进的目录项”
• “确定我们可能想要淘汰的使用率较低的目录项”
• “查找放弃率高的目录商品”
• “优化我们的硬件类别以改善用户体验”

变更管理示例

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

工作流管理示例

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

变更集管理示例

• “列出 ServiceNow 中的所有变更集”
• “显示由开发人员‘john.doe’创建的所有变更集”
• “获取有关变更集‘sys_update_set_123’的详细信息”
• “为‘HR Portal’应用程序创建一个新的变更集”
• “更新变更集‘sys_update_set_123’的描述”
• “提交变更集‘sys_update_set_123’并显示消息‘已修复登录问题’”
• “将变更集‘sys_update_set_123’发布到生产环境”
• “将文件添加到变更集‘sys_update_set_123’”
• “显示变更集‘sys_update_set_123’中的所有变更”

知识库示例

• “为IT部门创建新的知识库”
• “列出组织中的所有知识库”
• “在 IT 知识库中创建一个名为‘网络故障排除’的类别”
• “在网络故障排除类别中撰写一篇有关 VPN 设置的文章”
• “更新 VPN 设置文章以包含移动设备说明”
• “发布 VPN 设置文章，以便所有用户都可以看到”
• “列出网络故障排除类别中的所有文章”
• “显示 VPN 设置文章的详细信息”
• “在 IT 知识库中查找包含‘密码重置’的知识文章”
• “在网络故障排除类别下创建一个名为‘无线网络’的子类别”

用户管理示例

• “在放射科创建新用户 Alice 放射科医生”
• “更新 Bob 的用户记录，使他成为 Alice 的经理”
• “将 ITIL 角色分配给 Bob，以便他可以批准变更请求”
• “列出放射科的所有用户”
• “创建一个名为‘生物医学工程’的新小组来管理医疗设备”
• “将管理员用户添加为生物医学工程组成员”
• “更新生物医学工程组以更换其经理”
• “从生物医学工程组中删除用户”
• “查找系统中所有头衔中含有‘医生’的活跃用户”
• “创建一个作为放射科审批人的用户”
• “列出系统中的所有 IT 支持组”

UI 政策示例

• “为‘软件请求’项 (sys_id: abc...) 创建一个名为‘显示理由’的 UI 策略，该策略适用于‘software_cost’大于 100 的情况。”
• 对于 UI 策略‘显示理由’（sys_id：def...），添加一项操作以使‘business_justification’变量可见且强制执行。”
• “为策略‘显示理由’创建另一个操作以隐藏‘alternative_software’变量。”

示例脚本

该存储库包含演示如何使用这些工具的示例脚本：

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

身份验证方法

基本身份验证

OAuth 身份验证

API 密钥认证

发展

文档

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

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

故障排除

变更管理工具的常见错误

1. 错误： argument after ** must be a mapping, not CreateChangeRequestParams
   • 当您将CreateChangeRequestParams对象而不是字典传递给create_change_request函数时，就会发生此错误。
   • 解决方案：确保传递带有参数的字典，而不是 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 请求。

1. 分叉存储库
2. 创建你的功能分支（ git checkout -b feature/amazing-feature ）
3. 提交您的更改（ git commit -m 'Add some amazing feature' ）
4. 推送到分支（ git push origin feature/amazing-feature ）
5. 打开拉取请求

执照

该项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅 LICENSE 文件。