ServiceNow 的 MCP 服务器

ServiceNow 的 MCP 服务器是一个通用的、模块化的和可扩展的解决方案，旨在通过模型上下文协议 (MCP) 实现与 ServiceNow 的集成。它将一系列工具作为 API 公开，可用于各种用例，包括 ITSM、ITOM、SAM、HAM、增强型 CMDB、PPM、员工体验、报告、分析、动态工具注册和工作流编排。

此解决方案非常适合将 ServiceNow 与 AI 代理（例如，通过 n8n 等编排工具）或其他外部系统集成，以自动化访问配置、事件管理、资产生命周期管理等流程。

---

功能

• 通用 ServiceNow 客户端： 支持 CRUD 操作、基于查询的记录检索以及基本身份验证和 OAuth。

• 模块化架构： 用于 ITSM、ITOM、SAM、HAM、增强型 CMDB、PPM、员工体验、报告、分析、动态工具和工作流的独立模块。

• 增强型 CMDB： 结合了数据验证、重复数据删除、关系管理、丰富和审计日志记录，以确保数据完整性。

• 动态工具注册： 允许在运行时注册、注销和列出动态工具。

• 工作流编排： 提供专用工作流模块来协调复杂的多步骤流程。

• 丰富的提示模板： 使用可配置的提示模板与 AI 代理进行动态交互。

---

目录结构

mcp_servicenow/
├── main.py                     # MCP 服务器的入口点；通过 MCP 公开所有工具
├── config.py                   # ServiceNow 实例和身份验证的配置
├── server/
│   ├── __init__.py             # 服务器模块的包初始化程序
│   ├── base.py                 # 通用辅助函数和错误处理
│   ├── itsm.py                 # ITSM 操作（事件 CRUD 函数）
│   ├── itom.py                 # ITOM 操作（创建事件）
│   ├── sam.py                  # SAM 操作（管理许可证记录）
│   ├── ham.py                  # HAM 操作（资产生命周期管理）
│   ├── cmdb.py                 # **增强型** CMDB 函数（验证、重复数据删除、关系、丰富、日志记录）
│   ├── ppm.py                  # PPM 操作（项目记录）
│   ├── employee_experience.py  # 员工体验工具（反馈管理）
│   ├── reporting.py            # 报告工具（事件和变更报告）
│   ├── analytics.py            # 分析工具（趋势预测、异常检测）
│   ├── dynamic_tools.py        # 在运行时动态注册新工具
│   └── workflow.py             # 用于多步骤流程（例如，访问配置）的工作流编排
├── servicenow_client/
│   ├── __init__.py             # ServiceNow 客户端模块的包初始化程序
│   └── sn_client.py            # ServiceNow API 客户端（CRUD、查询、基本身份验证和 OAuth 支持）
└── prompts/
    ├── __init__.py             # 提示模板的包初始化程序
    └── templates.py            # 用于动态交互的丰富提示模板

---

安装和设置

先决条件

• Python 3.7 或更高版本
• 必需的库（通过 pip 安装）：
  • requests
  • fastapi（如果您选择稍后集成任何基于 FastAPI 的接口）
  • uvicorn
  • MCP SDK 所需的任何其他库

安装说明

1. 克隆存储库：

   git clone https://github.com/yourusername/mcp-servicenow.git
   cd mcp-servicenow
   

2. 创建并激活虚拟环境：

   python -m venv venv
   source venv/bin/activate  # 在 Windows 上：venv\Scripts\activate
   

3. 安装依赖项：

   创建一个包含以下条目的 requirements.txt 文件：

   requests
   fastapi
   uvicorn
   

   然后运行：

   pip install -r requirements.txt
   

4. 配置服务器：

   • 打开 config.py 并更新：
     • 使用您的 ServiceNow 实例 URL 更新 SN_INSTANCE_URL。
     • 将 SN_AUTH_METHOD 设置为 "basic" 或 "oauth"，并提供相应的凭据。

5. 运行 MCP 服务器：

   python main.py
   

   这将使用标准 I/O 传输启动 MCP 服务器（非常适合开发和测试）。

---

详细文档 – 与 MCP 服务器交互

MCP 服务器将其功能公开为“工具”，这些工具通过发送 JSON 有效负载来调用。每个工具代表一个动作（例如，创建事件、更新 CI、处理工作流），并包括一个定义其参数的输入模式。

以下是每个工具类别的详细信息。

---

1. ITSM 工具

itsm_create_incident

• 目的： 在 ServiceNow 中创建一个新的 ITSM 事件。

• 输入模式：

  • short_description（字符串，必需）
  • caller_id（字符串，必需）
  • priority（字符串，可选）

• 示例：

  {
    "name": "itsm_create_incident",
    "arguments": {
      "short_description": "无法访问内部门户",
      "caller_id": "user123",
      "priority": "High"
    }
  }
  

• 详细信息： 调用 create_incident() 向 ServiceNow 发送 REST API 调用，返回事件的唯一 sys_id 和确认详细信息。

itsm_read_incident

• 目的： 通过 sys_id 检索事件的详细信息。

• 输入模式：

  • sys_id（字符串，必需）

• 示例：

  {
    "name": "itsm_read_incident",
    "arguments": {
      "sys_id": "abc123xyz"
    }
  }
  

• 详细信息： 使用 read_incident() 执行 GET 操作，返回事件数据。

itsm_update_incident

• 目的： 更新现有事件。

• 输入模式：

  • sys_id（字符串，必需）
  • data（对象，必需）

• 示例：

  {
    "name": "itsm_update_incident",
    "arguments": {
      "sys_id": "abc123xyz",
      "data": {"comments": "已升级到支持部门。", "state": "In Progress"}
    }
  }
  

• 详细信息： 调用 update_incident() 以更新事件字段并记录更改。

itsm_delete_incident

• 目的： 通过 sys_id 删除事件。

• 输入模式：

  • sys_id（字符串，必需）

• 示例：

  {
    "name": "itsm_delete_incident",
    "arguments": {
      "sys_id": "abc123xyz"
    }
  }
  

• 详细信息： 调用 delete_incident() 以删除事件并记录删除。

---

2. 增强型 CMDB 工具

cmdb_create_ci

• 目的： 创建新的配置项 (CI) 记录。

• 输入模式：

  • name（字符串，必需）
  • ci_type（字符串，必需）
  • 其他可选字段（例如，制造商、位置）

• 示例：

  {
    "name": "cmdb_create_ci",
    "arguments": {
      "name": "Web Server 01",
      "ci_type": "Server",
      "manufacturer": "Dell",
      "location": "Data Center 1"
    }
  }
  

• 详细信息： 调用 create_ci() 以验证并在 ServiceNow 中创建 CI 记录，并记录该操作以进行审计。

cmdb_read_ci

• 目的： 使用其 sys_id 检索 CI 记录。

• 输入模式：

  • sys_id（字符串，必需）

• 示例：

  {
    "name": "cmdb_read_ci",
    "arguments": {
      "sys_id": "ci123abc"
    }
  }
  

• 详细信息： 执行 read_ci() 并返回 CI 的数据。

cmdb_update_ci

• 目的： 更新现有 CI 记录。

• 输入模式：

  • sys_id（字符串，必需）
  • data（对象，必需）

• 示例：

  {
    "name": "cmdb_update_ci",
    "arguments": {
      "sys_id": "ci123abc",
      "data": {"location": "Data Center 2", "status": "Active"}
    }
  }
  

• 详细信息： 调用 update_ci() 以更新并记录更改。

cmdb_delete_ci

• 目的： 删除 CI 记录。

• 输入模式：

  • sys_id（字符串，必需）

• 示例：

  {
    "name": "cmdb_delete_ci",
    "arguments": {
      "sys_id": "ci123abc"
    }
  }
  

• 详细信息： 调用 delete_ci() 以删除记录并记录删除。

cmdb_query_ci

• 目的： 根据自定义条件查询 CI 记录。

• 输入模式：

  • query（字符串，可选）
  • limit（数字，可选）
  • offset（数字，可选）

• 示例：

  {
    "name": "cmdb_query_ci",
    "arguments": {
      "query": "ci_type=Server",
      "limit": 50,
      "offset": 0
    }
  }
  

• 详细信息： 使用 query_ci() 返回与查询匹配的 CI 记录列表。

cmdb_deduplicate

• 目的： 扫描重复的 CI 记录。

• 输入模式： 不需要参数。

• 示例：

  {
    "name": "cmdb_deduplicate",
    "arguments": {}
  }
  

• 详细信息： 执行 deduplicate_ci() 并返回任何潜在的重复项。

cmdb_add_relationship

• 目的： 在两个 CI 之间添加关系。

• 输入模式：

  • ci_sys_id（字符串，必需）
  • related_ci_sys_id（字符串，必需）
  • relationship_type（字符串，可选；默认为“Depends on”）

• 示例：

  {
    "name": "cmdb_add_relationship",
    "arguments": {
      "ci_sys_id": "ci123abc",
      "related_ci_sys_id": "ci456def",
      "relationship_type": "Contains"
    }
  }
  

• 详细信息： 调用 add_relationship() 以创建关系并记录操作。

cmdb_get_relationships

• 目的： 检索特定 CI 的关系。

• 输入模式：

  • ci_sys_id（字符串，必需）

• 示例：

  {
    "name": "cmdb_get_relationships",
    "arguments": {
      "ci_sys_id": "ci123abc"
    }
  }
  

• 详细信息： 执行 get_relationships() 以返回所有子关系。

cmdb_enrich_ci

• 目的： 使用其他数据丰富 CI 记录。

• 输入模式：

  • sys_id（字符串，必需）
  • enrichment_data（对象，必需）

• 示例：

  {
    "name": "cmdb_enrich_ci",
    "arguments": {
      "sys_id": "ci123abc",
      "enrichment_data": {"warranty_expiration": "2025-12-31", "vendor": "Dell"}
    }
  }
  

• 详细信息： 调用 enrich_ci() 以使用额外信息更新记录并记录丰富。

---

3. ITOM、SAM、HAM 和 PPM 工具

itom_create_event

• 目的： 创建 ITOM 事件（例如，系统警报）。

• 输入模式：

  • event_description（字符串，必需）

• 示例：

  {
    "name": "itom_create_event",
    "arguments": {
      "event_description": "服务器 CPU 使用率超过阈值"
    }
  }
  

• 详细信息： 调用 create_event() 以在 ServiceNow 中记录 ITOM 事件。

sam_create_license

• 目的： 创建 SAM 许可证记录。

• 输入模式：

  • license_name（字符串，必需）
  • assigned_to（字符串，必需）

• 示例：

  {
    "name": "sam_create_license",
    "arguments": {
      "license_name": "Adobe Creative Cloud",
      "assigned_to": "marketing_team"
    }
  }
  

• 详细信息： 调用 create_license() 以注册许可证详细信息。

ham_create_asset

• 目的： 创建新的 HAM 资产记录。

• 输入模式：

  • asset_tag（字符串，必需）
  • model（字符串，必需）

• 示例：

  {
    "name": "ham_create_asset",
    "arguments": {
      "asset_tag": "ASSET001",
      "model": "Lenovo ThinkCentre"
    }
  }
  

• 详细信息： 调用 create_asset() 以添加新资产。

ppm_create_project

• 目的： 创建用于项目组合管理的项目。

• 输入模式：

  • project_name（字符串，必需）
  • owner（字符串，必需）

• 示例：

  {
    "name": "ppm_create_project",
    "arguments": {
      "project_name": "网站改版",
      "owner": "Project_Manager_01"
    }
  }
  

• 详细信息： 使用 create_project() 记录新项目。

---

4. 员工体验工具

ee_get_feedback

• 目的： 检索员工反馈。

• 输入模式：

  • query（字符串，可选；默认值：“active=true”）
  • limit（数字，可选；默认值：100）
  • offset（数字，可选）

• 示例：

  {
    "name": "ee_get_feedback",
    "arguments": {
      "query": "rating>=4",
      "limit": 50,
      "offset": 0
    }
  }
  

• 详细信息： 调用 get_employee_feedback() 并返回匹配的反馈记录。

ee_create_feedback

• 目的： 创建新的员工反馈记录。

• 输入模式：

  • employee_id（字符串，必需）
  • feedback（字符串，必需）
  • rating（数字，可选）

• 示例：

  {
    "name": "ee_create_feedback",
    "arguments": {
      "employee_id": "emp1001",
      "feedback": "新门户非常用户友好。",
      "rating": 5
    }
  }
  

• 详细信息： 调用 create_employee_feedback() 以存储反馈。

---

5. 报告和分析工具

report_generate_incident

• 目的： 生成事件报告。

• 输入模式：

  • query（字符串，可选）
  • limit（数字，可选）

• 示例：

  {
    "name": "report_generate_incident",
    "arguments": {
      "query": "priority=High",
      "limit": 100
    }
  }
  

• 详细信息： 调用 generate_incident_report() 以返回事件计数及其详细信息。

report_generate_change

• 目的： 生成变更请求报告。

• 输入模式：

  • query（字符串，可选）
  • limit（数字，可选）

• 示例：

  {
    "name": "report_generate_change",
    "arguments": {
      "query": "state=approved",
      "limit": 50
    }
  }
  

• 详细信息： 调用 generate_change_report() 并返回变更报告。

analytics_predict_trends

• 目的： 根据历史数据预测事件趋势。

• 输入模式：

  • query（字符串，可选）
  • limit（数字，可选）

• 示例：

  {
    "name": "analytics_predict_trends",
    "arguments": {
      "query": "active=true",
      "limit": 100
    }
  }
  

• 详细信息： 调用 predict_incident_trends() 以提供预测（例如，高趋势与低趋势）。

analytics_anomaly_detection

• 目的： 检测事件数据中的异常。

• 输入模式：

  • query（字符串，可选）
  • limit（数字，可选）

• 示例：

  {
    "name": "analytics_anomaly_detection",
    "arguments": {
      "query": "active=true",
      "limit": 100
    }
  }
  

• 详细信息： 调用 anomaly_detection() 以标记异常事件计数。

---

6. 工作流工具

workflow_process_access

• 目的： 编排多步骤访问配置流程。此过程包括：

  • 获取请求详细信息： 使用 ITSM 工具检索访问配置请求 (RITM)。
  • 角色分类： 分析请求以确定所需的角色。
  • 角色识别和分配： 将识别的角色与可用组匹配。
  • 审批触发： 通知相关组经理进行审批。
  • 角色分配和更新： 将用户分配到组并更新请求。
  • 完成： 在成功访问配置后关闭请求。

• 输入模式：

  • ritm_id（字符串，必需）
  • user_id（字符串，必需）

• 示例：

  {
    "name": "workflow_process_access",
    "arguments": {
      "ritm_id": "ritm789xyz",
      "user_id": "user123"
    }
  }
  

• 详细信息： 该工具从工作流模块调用 process_access_provisioning()，该模块将多个内部函数链接在一起，以完全自动化和记录访问配置过程的每个步骤。

---

如何调用这些工具

每个工具都通过发送 JSON 有效负载来调用，该有效负载包括工具的 name 和一个遵循工具输入模式的 arguments 对象。例如，使用 MCP 客户端或与 n8n 等工作流引擎集成，您可以发送：

{
  "name": "itsm_create_incident",
  "arguments": {
    "short_description": "无法访问内部门户",
    "caller_id": "user123",
    "priority": "High"
  }
}

服务器处理请求并返回包含结果、状态消息、唯一 ID 或错误详细信息的 JSON 响应。

---

最终总结

本文档概述了与 ServiceNow 的 MCP 服务器交互的综合指南。每个工具都详细描述了其目的、输入参数、使用示例和操作详细信息。无论您是管理 ITSM 事件、利用增强的 CMDB 功能、处理员工反馈、生成报告、分析数据还是编排复杂的工作流，此 MCP 服务器都提供了一个强大且可扩展的基础。

---

贡献

欢迎贡献！如果您想添加新功能、改进现有模块或集成其他功能（例如，增强的 AI 代理集成或进一步的 CMDB 增强），请打开一个 issue 或提交一个 pull request。

---