AI导哈

ServiceNow MCP服务器

一个用于ServiceNow的模型完成协议(MCP)服务器实现，允许Claude与ServiceNow实例进行交互，提供数据查询、记录操作和工作流执行等功能。

  • by echelon-ai-labs
  • Python
  • 本地部署
  • 303 星标
  • 更新于
在 GitHub 查看 echelon-ai-labs/servicenow-mcp

使用说明

ServiceNow MCP 服务器

一个为ServiceNow实现的模型完成协议（MCP）服务器，使Claude能够与ServiceNow实例进行交互。

概述

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

特点/功能

  • 使用各种身份验证方法（基本、OAuth、API密钥）连接到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. 创建一个 .env 使用您的ServiceNow凭据进行文件操作：

    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）进行通信，从而提供了更灵活的集成选项。

启动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服务器支持加载称为“包”的工具子集。这可以通过以下方式控制： 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用于创建和管理服务目录项、类别、变量以及相关脚本（用户界面策略、用户条件）的工具。
  • change_coordinator用于管理变更请求生命周期的工具，包括任务和审批流程。
  • knowledge_author用于创建和管理知识库、分类及文章的工具。
  • platform_developer服务器端脚本编写（脚本包含）、工作流开发和部署（更改集）的工具。
  • system_administrator用户/组管理工具和查看系统日志的功能。
  • agile_management用于管理用户故事、史诗（Epic）、Scrum任务和项目的工具。
  • full包含所有可用工具（默认设置）。
  • none不包含任何工具（除……外） list_tool_packages）。

内省工具

  • **list_tool_packages**列出配置中定义的所有可用工具包名称，并显示当前加载的工具包。此工具在所有工具包中均可使用，除了 none.

可用工具

注： 以下工具的可用性取决于已加载的工具包（参见上文的“工具打包”部分）。默认情况下（full （打包后），所有工具均可使用。

事件管理工具

  1. 创建事件 - 在ServiceNow中创建一个新事件
  2. 更新事件 - 在ServiceNow中更新现有的事件
  3. 添加评论 - 在ServiceNow中为事件添加注释
  4. 解决事件 - 在ServiceNow中解决一个事件
  5. 列出事件 - 从ServiceNow列出事件

服务目录工具

  1. 列出目录项 - 列出ServiceNow中的服务目录项目
  2. 获取目录项 - 从ServiceNow获取特定的服务目录项
  3. 列出目录类别 - 列出ServiceNow中的服务目录类别
  4. 创建目录类别 - 在ServiceNow中创建一个新的服务目录类别
  5. 更新目录类别 - 在ServiceNow中更新现有的服务目录类别
  6. 移动目录项 - 在ServiceNow中在不同类别之间移动目录项
  7. 创建目录项变量 - 为目录项创建一个新的变量（表单字段）
  8. 列出目录项变量 - 列出目录项的所有变量
  9. 更新目录项变量 - 更新目录项的现有变量
  10. 列出目录列表 - 列出ServiceNow中的服务目录

目录优化工具

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

变革管理工具

  1. 创建变更请求 - 在ServiceNow中创建一个新的变更请求
  2. 更新更改请求 - 更新现有的变更请求
  3. 列表变更请求 - 列出变更请求并提供过滤选项
  4. 获取变更请求详情 - 获取特定变更请求的详细信息
  5. 添加更改任务 - 在变更请求中添加任务
  6. 提交更改以待审批 - 提交变更请求以待批准
  7. 批准更改 - 批准变更请求
  8. 拒绝更改 - 拒绝更改请求

敏捷管理工具

故事管理
  1. 创作故事 - 在ServiceNow中创建一个新的用户故事
  2. 更新故事 - 在ServiceNow中更新现有的用户故事
  3. 故事列表 - 列出用户故事并提供过滤选项
  4. 创建故事依赖关系 - 在两个故事之间建立依赖关系
  5. 删除故事依赖关系 - 删除故事之间的依赖关系
史诗管理
  1. 创建史诗级任务/故事线 - 在ServiceNow中创建一个新的史诗（Epic）
  2. 更新史诗（或“重大更新”） - 在ServiceNow中更新现有的史诗（Epic）
  3. 史诗列表 - 列出ServiceNow中的史诗故事（Epic），并提供过滤选项
Scrum任务管理
  1. 创建敏捷任务 - 在ServiceNow中创建一个新的Scrum任务
  2. 更新敏捷任务 - 在ServiceNow中更新现有的Scrum任务
  3. 列出Scrum任务 - 从ServiceNow列出Scrum任务，并提供过滤选项
项目管理
  1. 创建项目 - 在ServiceNow中创建一个新项目
  2. 更新项目 - 在ServiceNow中更新现有项目
  3. 列出项目 - 列出ServiceNow中的项目，并提供筛选选项

工作流管理工具

  1. 列出工作流 - 列出ServiceNow中的工作流
  2. 获取工作流 - 从ServiceNow获取特定的工作流
  3. 创建工作流 - 在ServiceNow中创建一个新的工作流
  4. 更新工作流 - 在ServiceNow中更新现有工作流
  5. 删除工作流 - 从ServiceNow中删除工作流

脚本包含管理工具

  1. 列出脚本包含项 - 列表脚本包含来自ServiceNow的内容
  2. 获取脚本包含（或：获取脚本引入） - 从ServiceNow获取特定的脚本包含（或脚本引用）
  3. 创建脚本包含（或：创建脚本导入） - 在ServiceNow中创建一个新的脚本包含项
  4. 更新脚本包含 - 在ServiceNow中更新现有的脚本包含项
  5. 删除脚本包含 - 从ServiceNow中删除脚本包含项

更改集管理工具

  1. 列出更改集 - 列出ServiceNow中的更改集，并提供过滤选项
  2. 获取更改集详情 - 获取特定更改集的详细信息
  3. 创建更改集 - 在ServiceNow中创建一个新的更改集
  4. 更新更改集 - 更新现有的更改集
  5. 提交更改集 - 提交更改集
  6. 发布更改集 - 发布更改集
  7. 将文件添加到更改集中 - 将文件添加到更改集中

知识库管理工具

  1. 创建知识库 - 在ServiceNow中创建一个新的知识库
  2. 知识库列表 - 列出带有过滤选项的知识库
  3. 创建类别 - 在知识库中创建一个新类别
  4. 创建文章 - 在ServiceNow中创建一篇新的知识文章
  5. 更新文章 - 在ServiceNow中更新现有的知识文章
  6. 发布文章 - 在ServiceNow中发布一篇知识文章
  7. 文章列表 - 列出知识文章，并提供过滤选项
  8. 获取文章 - 通过ID获取特定的知识文章

用户管理工具

  1. 创建用户 - 在ServiceNow中创建一个新用户
  2. 更新用户 - 在ServiceNow中更新现有用户
  3. 获取用户 - 通过ID、用户名或电子邮件获取特定用户
  4. 列出用户 - 列出用户并提供筛选选项
  5. 创建群组 - 在ServiceNow中创建一个新组
  6. 更新群组 - 在ServiceNow中更新现有组
  7. 添加群组成员 - 在ServiceNow中向组添加成员
  8. 移除群组成员 - 在ServiceNow中从组中移除成员
  9. 列出群组 - 列出带有过滤选项的组

用户界面策略工具

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

使用MCP CLI（MCP命令行界面）

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桌面版的集成

在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"
      }
    }
  }
}
  1. 重启 Claude 桌面应用以应用更改

与Claude的示例用法

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

事件管理示例

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

服务目录示例

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

目录优化示例

  • “分析我们的服务目录，并找出改进的机会”
  • “查找描述不佳、需要改进的目录项”
  • “识别出使用率较低的目录项目，这些项目我们可能希望停用”
  • “查找放弃率较高的目录项目”
  • “优化我们的硬件类别以提升用户体验”

变革管理示例

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

敏捷管理示例

  • “创建一个新的用户故事，用于实现一个新的报告仪表板”
  • “更新‘实施新的报告仪表板’故事，将其设置为阻塞状态”
  • “列出分配给数据分析团队的所有用户故事”
  • “在‘实现新的报告仪表板’故事和‘开发数据提取管道’故事之间建立依赖关系”
  • “删除‘实现新的报告仪表板’故事与‘开发数据提取管道’故事之间的依赖关系”
  • “创建一个新的史诗级项目，名为‘数据分析倡议’”
  • “将‘数据分析倡议’史诗任务更新为已完成状态”
  • “列出‘数据分析’项目中的所有史诗级任务（或大型任务）”
  • “为‘实现新的报告仪表板’故事创建一个新的敏捷任务”
  • “将‘开发数据提取管道’的Scrum任务更新为已完成状态”
  • “在‘实现新报告仪表板’故事中列出所有Scrum任务”
  • “创建一个名为‘数据分析项目’的新项目”
  • “更新‘数据分析项目’，将其状态设为已完成”
  • “列出‘数据分析’史诗（或大项目）中的所有项目”

工作流管理示例

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

更改集管理示例

  • “列出ServiceNow中的所有更改集”
  • “显示由开发者‘john.doe’创建的所有更改集”
  • “获取关于更改集 'sys_update_set_123' 的详细信息”
  • “为‘人力资源门户’应用程序创建一个新的更改集”
  • “更新更改集 '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的新用户”
  • “更新鲍勃的用户记录，使他成为爱丽丝的经理”
  • “将ITIL角色分配给鲍勃，以便他可以批准变更请求”
  • “列出放射科的所有用户”
  • “创建一个名为‘生物医学工程’的新群组，用于管理医疗器械”
  • “将管理员用户添加为生物医学工程组的成员”
  • “通知生物医学工程团队更换其经理”
  • “将用户从生物医学工程组中移除”
  • “查找系统中所有职称中包含‘医生’的活跃用户”
  • “创建一个用户，该用户将作为放射科的审批人”
  • “列出系统中所有的IT支持团队”

UI策略示例

  • “为‘软件请求’项目（sys_id: abc...）创建一个名为‘显示理由’的用户界面策略，当‘software_cost’大于100时适用。”
  • “对于用户界面策略‘显示理由’（sys_id: def...），添加一个操作以使‘business_justification’变量可见且为必填项。”
  • “为‘显示理由’策略创建另一个操作，以隐藏‘替代软件’变量。”

示例脚本

该仓库包含示例脚本，展示了如何使用这些工具：

  • 示例/目录优化示例.py展示如何分析并优化ServiceNow服务目录
  • 示例/变更管理演示.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 参数需按正确顺序排列。函数已更新，可自动处理参数交换。

做出贡献

欢迎贡献！请随时提交拉取请求。

  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文件了解详情。

相关 MCP