ServiceNow MCP 服务器

这是一个为 ServiceNow 实现的 Model Completion Protocol (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  # 在 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 服务器运行，使用 Server-Sent Events (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/ - 向服务器发送消息的端点

示例

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

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 服务器提供了以下工具：

事件管理工具

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 安装，它提供了一种方便的方式来将服务器注册到 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. 编辑位于 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或适合您操作系统的相应路径下的 Claude Desktop 配置文件：

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

1. 重启 Claude Desktop 以应用更改

通过 Claude 使用示例

一旦 ServiceNow MCP 服务器配置好并与 Claude Desktop 集成后，您可以要求 Claude 执行如下操作：

事件管理示例

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

服务目录示例

• "显示服务目录中的所有项目"
• "列出所有服务目录类别"
• "获取笔记本电脑请求目录项的详细信息"
• "显示硬件类别中的所有目录项"
• "在服务目录中搜索'software'"
• "在服务目录中创建一个名为'Cloud Services'的新类别"
• "将'Hardware'类别重命名为'IT Equipment'"
• "将'Virtual Machine'目录项移动到'Cloud Services'类别"
• "在'IT Equipment'类别下创建一个名为'Monitors'的子类别"
• "通过将所有软件项目移动到'Software'类别来重组我们的目录"
• "为笔记本电脑请求目录项创建描述字段"
• "向目录项添加选择笔记本型号的下拉字段"
• "列出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. 分叉仓库
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 文件。