ServiceNow MCP 服务器

一个用于 ServiceNow 的模型补全协议 (MCP) 服务器实现，允许 Claude 与 ServiceNow 实例交互。

<a href="https://glama.ai/mcp/servers/@osomai/servicenow-mcp"> <img width="380" height="200" src="https://glama.ai/mcp/servers/@osomai/servicenow-mcp/badge" alt="ServiceNow Server MCP server" /> </a>

概述

本项目实现了一个 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  # 在 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  # 或 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 服务器也可以作为 Web 服务器运行，使用服务器发送事件 (SSE) 进行通信，从而实现更灵活的集成选项。

启动 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

# 创建服务器配置
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 服务器
servicenow_mcp = ServiceNowMCP(config)

# 创建带有 SSE 传输的 Starlette 应用程序
app = create_starlette_app(servicenow_mcp, debug=True)

# 启动 Web 服务器
uvicorn.run(app, host="0.0.0.0", port=8080)

可用工具

ServiceNow MCP 服务器提供以下工具：

事件管理工具

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 - 更新目录项的现有变量

目录优化工具

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. 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 - 列出带有过滤选项的组

使用 MCP CLI

ServiceNow MCP 服务器可以与 MCP CLI 一起安装，MCP CLI 提供了一种方便的方式来向 Claude 注册服务器。

# 使用来自 .env 文件的环境变量安装 ServiceNow MCP 服务器
mcp install src/servicenow_mcp/server.py -f .env

此命令将向 Claude 注册 ServiceNow MCP 服务器，并将其配置为使用来自 .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 的示例用法

将 ServiceNow MCP 服务器与 Claude Desktop 配置好后，您可以要求 Claude 执行以下操作：

事件管理示例

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

服务目录示例

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

目录优化示例

• "分析我们的服务目录并确定改进机会"
• "查找描述不佳需要改进的目录项"
• "识别使用率较低可能需要停用的目录项"
• "查找放弃率高的目录项"
• "优化我们的硬件类别以改善用户体验"

变更管理示例

• "创建一个变更请求，用于明天晚上应用安全补丁的服务器维护"
• "安排下周二凌晨 2 点到 4 点的数据库升级"
• "向服务器维护变更添加一个任务，用于实施前检查"
• "提交服务器维护变更以供批准"
• "批准数据库升级变更，并评论：实施计划看起来很全面"
• "向我展示本周安排的所有紧急变更"
• "列出分配给网络团队的所有变更"

工作流管理示例

• "向我展示 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 知识库中查找包含“密码重置”的知识文章"
• "在“网络故障排除”类别下创建一个名为“无线网络”的子类别"

用户管理示例

• "在放射科创建一个新用户 Dr. Alice Radiology"
• "更新 Bob 的用户记录，使其成为 Alice 的经理"
• "将 ITIL 角色分配给 Bob，以便他可以批准变更请求"
• "列出放射科的所有用户"
• "创建一个名为“生物医学工程”的新组，用于管理医疗设备"
• "将管理员用户作为成员添加到生物医学工程组"
• "更新生物医学工程组以更改其经理"
• "从生物医学工程组中删除用户"
• "查找系统中标题中包含“doctor”的所有活动用户"
• "创建一个将作为放射科审批者的用户"
• "列出系统中的所有 IT 支持组"

示例脚本

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

• 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

   • 当您将 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 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 文件。