内容
# 🚀 ServiceNow MCP 服务器
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/sudhanshu-singh22/ServiceNow_MCP)
[](https://modelcontextprotocol.io/)
一个**生产就绪的模型上下文协议（MCP）服务器**，它将 ServiceNow 开发能力暴露为 AI 可调用的工具。连接任何与 MCP 兼容的 AI 代理（Claude Desktop、Claude Code 或自定义实现）到您的 ServiceNow 实例，并通过自然语言自动执行实际开发任务。
---
## 📋 目录
- [项目概述](#-项目概述)
- [功能](#-功能)
- [架构](#-架构)
- [安装](#-安装)
- [配置](#-配置)
- [环境变量](#-环境变量)
- [使用示例](#-使用示例)
- [MCP 客户端配置](#-mcp-客户端配置)
- [可用工具](#-可用工具)
- [文件夹结构](#-文件夹结构)
- [安全考虑](#-安全考虑)
- [开发设置](#-开发设置)
- [贡献](#-贡献)
- [路线图](#-路线图)
- [许可证](#-许可证)
---
## 🎯 项目概述
### 什么是 MCP 服务器？
**模型上下文协议（MCP）**是一种标准化接口，允许 AI 代理访问外部工具和数据源。MCP 服务器充当 AI 客户端和后端系统之间的桥梁，将业务逻辑暴露为可调用函数。
### 本服务器的作用
ServiceNow MCP 服务器使以下功能成为可能：
- **🤖 AI 驱动的开发**：让 AI 代理编写 ServiceNow 代码、创建表、配置业务规则和管理工作流
- **⚙️ 表管理**：创建和管理自定义表、字段和数据模型
- **🔐 访问控制**：以编程方式定义 ACL 和授权规则
- **🔄 工作流自动化**：触发 Flow Designer 流并监控执行
- **📊 数据操作**：使用 GlideRecord 样式的查询来查询、创建、更新和删除记录
- **💼 业务逻辑**：创建业务规则、脚本包含和脚本化 REST API
- **📥 批量操作**：管理导入集和转换映射
### 关键优势
✅ **21 个预建工具**，涵盖核心 ServiceNow 操作
✅ **多种身份验证方法**（基本身份验证、OAuth 2.0、Bearer Token、API Key）
✅ **自动重试逻辑**，具有指数退避
✅ **结构化日志**，用于调试和监控
✅ **生产级**，具有错误处理和验证
✅ **异步/等待**，用于高性能并发请求
---
## ✨ 功能
| 类别 | 可用工具 | 数量 |
|---|---|---|
| **表管理** | `create_table`, `list_tables` | 2 |
| **字段/字典** | `create_field`, `read_dictionary` | 2 |
| **GlideRecord 查询** | `query_records`, `get_record`, `update_record`, `delete_record` | 4 |
| **业务规则** | `create_business_rule`, `list_business_rules` | 2 |
| **脚本包含** | `create_script_include`, `list_script_includes` | 2 |
| **访问控制** | `create_acl`, `list_acls` | 2 |
| **Flow Designer** | `trigger_flow`, `get_flow_execution_status`, `list_flows` | 3 |
| **导入集** | `create_import_set_table`, `run_import_set`, `list_transform_maps` | 3 |
| **脚本化 REST API** | `call_scripted_rest_api`, `list_scripted_rest_apis`, `get_scripted_rest_resources` | 3 |
| | **总数** | **21 个工具** |
---
## 🏗️ 架构
### 系统设计
```
┌─────────────────────────────────────────────────────────┐
│ AI 代理 │
│ （Claude、Claude Code、自定义） │
└────────────────────────┬────────────────────────────────┘
│ MCP 协议
▼
┌─────────────────────────────────────────────────────────┐
│ ServiceNow MCP 服务器 │
├─────────────────────────────────────────────────────────┤
│ ┌────────────────────────────────────────────────────┐ │
│ │ 工具注册表（21 个工具） │ │
│ │ - 表、字段、记录、业务规则 │ │
│ │ - ACL、工作流、导入集、REST API │ │
│ └────────────────────────────────────────────────────┘ │
│ │ │
│ ┌────────────────────▼────────────────────────────┐ │
│ │ ServiceNowClient（异步） │ │
│ │ - 身份验证方法（基本/OAuth/Bearer/API Key） │ │
│ │ - 重试逻辑（Tenacity） │ │
│ │ - 请求/响应处理 │ │
│ └────────────────────────────────────────────────┘ │
│ │ │
│ ┌────────────────────▼────────────────────────────┐ │
│ │ 配置管理器（Pydantic） │ │
│ │ - 环境验证 │ │
│ │ - 身份验证凭证管理 │ │
│ │ - 日志配置 │ │
│ └────────────────────────────────────────────────┘ │
└────────────────────────┬────────────────────────────────┘
│ HTTPS/REST
▼
┌─────────────────────────────────────────────────────────┐
│ ServiceNow 实例 REST API │
│ （v1 或 v2） │
└─────────────────────────────────────────────────────────┘
```
### 核心组件
| 组件 | 目的 | 关键功能 |
|---|---|---|
| **server.py** | MCP 服务器和工具注册表 | 主入口点，21 个工具定义，SSE 消息处理 |
| **client.py** | 异步 HTTP 客户端 | 身份验证处理、重试逻辑、速率限制处理 |
| **config.py** | 配置管理 | 基于 Pydantic 的设置，4 种身份验证方法，验证 |
| **logger.py** | 结构化日志记录 | JSON 格式的日志输出到 stderr，可配置的日志级别 |
| **tools/** | 工具实现 | 按域组织的模块化工具定义 |
### 身份验证流程
```
请求流程：
┌─────────────────────────────────────────────────────┐
│ 1. 工具从 AI 代理接收参数 │
│ 2. 通过 Pydantic 模型验证 │
│ 3. 调用 ServiceNowClient._request() │
│ 4. 注入身份验证标头 (_auth_headers) │
│ 5. 基本身份验证通过 httpx.BasicAuth（如果基本） │
│ 6. Tenacity 重试装饰器应用 │
│ 7. 发送 HTTP 请求并设置超时 │
│ 8. 解析并返回响应 │
└─────────────────────────────────────────────────────┘
```
---
## 📦 安装
### 先决条件
- **Python 3.11+** – 异步/等待功能所需
- **ServiceNow 实例** – 可在 https://developer.servicenow.com 获取开发者沙盒
- **互联网访问** – 用于与 ServiceNow REST API 通信
- **Git** – 用于克隆存储库
### 步骤 1：克隆存储库
```bash
git clone https://github.com/sudhanshu-singh22/ServiceNow_MCP.git
cd ServiceNow_MCP
```
### 步骤 2：创建虚拟环境
```bash
python -m venv .venv
```
### 步骤 3：激活虚拟环境
**Windows:**
```bash
.venv\Scripts\activate
```
**macOS / Linux:**
```bash
source .venv/bin/activate
```
您应该在终端提示符开始处看到 `(.venv)`。
### 步骤 4：安装软件包
```bash
pip install -e .
```
此命令以可编辑模式安装软件包以及所有依赖项：
- `mcp>=1.0.0` – 模型上下文协议
- `httpx>=0.27.0` – 异步 HTTP 客户端
- `tenacity>=9.0.0` – 重试库
- `pydantic>=2.7.0` – 数据验证
- `pydantic-settings>=2.3.0` – 配置管理
- `python-dotenv>=1.0.0` – 环境变量加载
### 步骤 5：配置环境
```bash
# Windows
copy .env.example .env
# macOS / Linux
cp .env.example .env
```
打开 `.env` 并填写您的 ServiceNow 实例 URL 和身份验证凭证（参见 [配置](#-配置) 部分）。
### 步骤 6：运行服务器
```bash
servicenow-mcp
```
或直接通过 Python：
```bash
python -m servicenow_mcp.server
```
预期输出：
```
2026-06-04 15:30:45,123 - servicenow_mcp.server - INFO - Initializing MCP server...
2026-06-04 15:30:45,234 - servicenow_mcp.server - INFO - ServiceNow MCP server started
```
服务器将在 **stdio** （标准输入/输出）上启动并等待 MCP 客户端连接。
### 快速启动验证
验证安装：
```bash
# 激活虚拟环境
source .venv/bin/activate # macOS/Linux
# 或
.venv\Scripts\activate # Windows
# 验证导入工作
python -c "from servicenow_mcp.server import main; print('✓ 安装成功')"
```
---
## ⚙️ 配置
### 概述
配置通过 `.env` 文件中的**环境变量**加载，使用 `pydantic-settings`。所有变量均以 `SERVICENOW_` 前缀（`LOG_LEVEL` 除外）。
### 配置来源（优先级顺序）
1. **`.env` 文件** – 默认配置
2. **环境变量** – 覆盖 `.env`
3. **代码中的默认值** – 备用值
### 必需配置
每个安装都必须设置：
```env
SERVICENOW_INSTANCE_URL=https://dev12345.service-now.com
SERVICENOW_AUTH_METHOD=basic # 或 oauth、bearer、api_key
```
然后为所选身份验证方法配置凭证（请参见下文）。
### 身份验证方法
#### 1️⃣ **基本身份验证**（推荐用于开发/沙盒）
```env
SERVICENOW_AUTH_METHOD=basic
SERVICENOW_USERNAME=admin
SERVICENOW_PASSWORD=your-password
```
**优点：** 设置简单，适用于开发/测试
**缺点：** 凭证为纯文本，不推荐用于生产
**何时使用：** 本地开发、沙盒
#### 2️⃣ **OAuth 2.0 客户端凭证**（推荐用于生产）
```env
SERVICENOW_AUTH_METHOD=oauth
SERVICENOW_OAUTH_CLIENT_ID=your-client-id
SERVICENOW_OAUTH_CLIENT_SECRET=your-client-secret
SERVICENOW_OAUTH_TOKEN_URL=https://your-instance.service-now.com/oauth_token.do
SERVICENOW_OAUTH_SCOPE=useraccount # 可选
```
**设置说明：
1. 在您的 ServiceNow 实例中，导航到 **系统 OAuth > 应用程序注册表**
2. 点击 **新建 > 创建外部客户端的 OAuth API 端点**
3. 填写表单：
- **名称**：ServiceNow MCP
- **活动**：✓
4. 复制 **客户端 ID** 和 **客户端密钥**
5. 将它们粘贴到您的 `.env` 文件中
**优点：** 安全的基于令牌的身份验证，支持基于范围的权限
**缺点：** 设置稍微复杂一些
**何时使用：** 生产、安全环境
#### 3️⃣ **Bearer Token / PAT**（静态令牌）
```env
SERVICENOW_AUTH_METHOD=bearer
SERVICENOW_BEARER_TOKEN=your-static-bearer-token
```
**设置说明：
1. 在 ServiceNow 中，导航到 **系统安全 > API 身份验证 > 令牌**
2. 为您的用户创建一个新的令牌
3. 复制令牌值
4. 粘贴到 `.env`
**优点：** 简单，适用于 CI/CD 管道
**缺点：** 静态令牌，需要手动轮换
**何时使用：** CI/CD、自动化部署
#### 4️⃣ **API Key**（自定义标头）
```env
SERVICENOW_AUTH_METHOD=api_key
SERVICENOW_API_KEY=your-api-key
SERVICENOW_API_KEY_HEADER=X-API-Key # 可选，默认为 X-API-Key
```
**优点：** 灵活，适用于任何自定义身份验证标头
**缺点：** 实现特定
**何时使用：** 自定义身份验证系统
---
## 🔧 环境变量
### 完整参考
| 变量 | 类型 | 必需 | 默认值 | 描述 |
|---|---|---|---|---|
| **核心** | | | | |
| `SERVICENOW_INSTANCE_URL` | URL | ✓ | — | ServiceNow 实例基本 URL（例如 `https://dev12345.service-now.com`） |
| `SERVICENOW_AUTH_METHOD` | 枚举 | | `basic` | 身份验证方法：`basic` \| `oauth` \| `bearer` \| `api_key` |
| `SERVICENOW_API_VERSION` | 字符串 | | `v2` | 表 API 版本：`v1` \| `v2` |
| `SERVICENOW_TIMEOUT_SECONDS` | 整数 | | `30` | HTTP 请求超时（1-300）秒 |
| `SERVICENOW_MAX_RETRIES` | 整数 | | `3` | 429/5xx 重试次数（0-10） |
| **基本身份验证** | | | | |
| `SERVICENOW_USERNAME` | 字符串 | 如果 basic | — | ServiceNow 用户名 |
| `SERVICENOW_PASSWORD` | 字符串 | 如果 basic | — | ServiceNow 密码 |
| **OAuth 2.0** | | | | |
| `SERVICENOW_OAUTH_CLIENT_ID` | 字符串 | 如果 oauth | — | OAuth 客户端 ID 来自应用程序注册表 |
| `SERVICENOW_OAUTH_CLIENT_SECRET` | 字符串 | 如果 oauth | — | OAuth 客户端密钥来自应用程序注册表 |
| `SERVICENOW_OAUTH_TOKEN_URL` | URL | 如果 oauth | — | OAuth 令牌端点 URL |
| `SERVICENOW_OAUTH_SCOPE` | 字符串 | | — | OAuth 范围（例如 `useraccount`） |
| **Bearer Token** | | | | |
| `SERVICENOW_BEARER_TOKEN` | 字符串 | 如果 bearer | — | 静态 bearer 令牌或 PAT |
| **API Key** | | | | |
| `SERVICENOW_API_KEY` | 字符串 | 如果 api_key | — | 自定义 API 密钥值 |
| `SERVICENOW_API_KEY_HEADER` | 字符串 | | `X-API-Key` | API 密钥的 HTTP 头名称 |
| **日志记录** | | | | |
| `LOG_LEVEL` | 枚举 | | `INFO` | 日志级别：`DEBUG` \| `INFO` \| `WARNING` \| `ERROR` |
### `.env` 文件示例
**开发（基本身份验证）：**
```env
SERVICENOW_INSTANCE_URL=https://dev12345.service-now.com
SERVICENOW_AUTH_METHOD=basic
SERVICENOW_USERNAME=admin
SERVICENOW_PASSWORD=devpassword123
LOG_LEVEL=DEBUG
```
**生产（OAuth）：**
```env
SERVICENOW_INSTANCE_URL=https://prod.service-now.com
SERVICENOW_AUTH_METHOD=oauth
SERVICENOW_OAUTH_CLIENT_ID=abc123def456
SERVICENOW_OAUTH_CLIENT_SECRET=secret789xyz
SERVICENOW_OAUTH_TOKEN_URL=https://prod.service-now.com/oauth_token.do
SERVICENOW_OAUTH_SCOPE=useraccount
SERVICENOW_TIMEOUT_SECONDS=60
SERVICENOW_MAX_RETRIES=5
LOG_LEVEL=INFO
```
---
## 💡 使用示例
### 1. 启动服务器
```bash
# 激活虚拟环境
source .venv/bin/activate # macOS/Linux
# 或
.venv\Scripts\activate # Windows
# 运行服务器
servicenow-mcp
```
### 2. 通过 AI 代理创建表
**提示：Claude：```
创建新的 ServiceNow 表用于管理员工设备请求。
表应：
- 扩展“任务”表
- 标为“设备请求”
- 表名：`u_equipment_request`
- 自动创建模块`
```
**幕后，MCP 服务器调用：
```json
### 1. 启动服务器
```bash
# 激活虚拟环境
source .venv/bin/activate # macOS/Linux
# 或
.venv\Scripts\activate # Windows
# 运行服务器
servicenow-mcp
```
### 2. 通过 AI 代理创建表
**提示：**
```
创建一张新的 ServiceNow 表，用于管理员工设备请求。
该表应：
- 扩展“任务”表
- 标为“设备请求”
- 表名：`u_equipment_request`
- 自动创建模块`
```
**幕后，MCP 服务器调用：
```json
{
"tool": "create_table",
"params": {
"label": "设备请求",
"name": "u_equipment_request",
"extends": "task",
"access": "public",
"create_module": true
}
}
```
### 3. 查询记录
**提示：**
```
获取所有优先级为 1 或 2 的活动事件，分配给任何人，
显示编号、描述、分配人员和优先级。限制为 20 个结果。
```
**MCP 工具调用：
```json
{
"tool": "query_records",
"params": {
"table": "incident",
"encoded_query": "active=true^ORpriority=1^ORpriority=2",
"fields": ["number", "short_description", "assigned_to", "priority"],
"limit": 20,
"order_by_desc": "sys_created_on"
}
}
```
### 4. 创建业务规则
**提示：**
```
在 Equipment Request 表上创建一个业务规则，该规则：
- 在插入或更新之前运行
- 将优先级设置为 2（中等），适用于所有新请求
- 如果未已设置，则将状态设置为“新建”
```
**MCP 工具调用：
```json
{
"tool": "create_business_rule",
"params": {
"name": "设置默认优先级和状态",
"table": "u_equipment_request",
"when": "before",
"on_insert": true,
"on_update": true,
"script": "if (!current.priority) current.priority = 2;\nif (!current.state) current.state = 'New';",
"active": true
}
}
```
### 5. 触发流程
**提示：**
```
为员工 ID EMP-12345 启动员工离职工作流，
最后一天为 2026-06-30
```
**MCP 工具调用：
```json
{
"tool": "trigger_flow",
"params": {
"flow_id": "global.employee_offboarding",
"inputs": {
"employee_id": "EMP-12345",
"last_day": "2026-06-30"
},
"wait_for_completion": false
}
}
```
### 6. 创建访问控制规则
**提示：**
```
在 Equipment Request 表上创建一个 ACL，允许：
- 管理员读取、写入和删除
- 经理读取和写入（基于其部门）
- 所有其他用户仅读取`
```
**MCP 工具调用：
```json
{
"tool": "create_acl",
"params": {
"operation": "write",
"table_name": "u_equipment_request",
"roles": ["admin", "manager"],
"script": "answer = gs.hasRole('admin') || (gs.hasRole('manager') && current.department == gs.getUser().department);",
"description": "管理员和部门经理可以编辑请求"
}
}
```
---
## 🔌 MCP 客户端配置
### Claude Desktop 集成
1. **查找您的 Claude Desktop 配置文件：**
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
2. **添加 MCP 服务器配置：
```json
{
"mcpServers": {
"servicenow": {
"command": "python",
"args": ["-m", "servicenow_mcp.server"],
"cwd": "/path/to/servicenow-mcp",
"env": {
"SERVICENOW_INSTANCE_URL": "https://your-instance.service-now.com",
"SERVICENOW_AUTH_METHOD": "basic",
"SERVICENOW_USERNAME": "admin",
"SERVICENOW_PASSWORD": "your-password"
}
}
}
}
```
3. **重启 Claude Desktop**
4. **验证连接：**
- 在 Claude Desktop 中，您应该看到 `servicenow` 在可用工具列表中
---
## 🔌 MCP 客户端配置
### 可用工具
| 类别 | 可用工具 | 数量 |
|---|---|---|
| **表管理** | `create_table`, `list_tables` | 2 |
| **字段/字典** | `create_field`, `read_dictionary` | 2 |
| **GlideRecord 查询** | `query_records`, `get_record`, `update_record`, `delete_record` | 4 |
| **业务规则** | `create_business_rule`, `list_business_rules` | 2 |
| **脚本包含** | `create_script_include`, `list_script_includes` | 2 |
| **访问控制** | `create_acl`, `list_acls` | 2 |
| **Flow Designer** | `trigger_flow`, `get_flow_execution_status`, `list_flows` | 3 |
| **导入集** | `create_import_set_table`, `run_import_set`, `list_transform_maps` | 3 |
| **脚本化 REST API** | `call_scripted_rest_api`, `list_scripted_rest_apis`, `get_scripted_rest_resources` | 3 |
| | **总数** | **21 个工具** |
---
## 🔧 安装
### 依赖项
- **Python 3.11+** – 异步/等待功能所需
- **一个 ServiceNow 实例** – 可在 https://developer.servicenow.com 获取开发者沙盒
- **互联网访问** – 用于与 ServiceNow REST API 通信
- **Git** – 用于克隆存储库
---
## 🚀 快速入门
### 1. 克隆存储库
```bash
git clone https://github.com/sudhanshu-singh22/ServiceNow_MCP.git
cd ServiceNow_MCP
```
### 2. 创建虚拟环境
```bash
python -m venv .venv
```
### 3. 激活虚拟环境
**Windows:**
```bash
.venv\Scripts\activate
```
**macOS / Linux:**
```bash
source .venv/bin/activate
```
您应该在终端提示符开始处看到 `(.venv)`。
### 4. 安装软件包
```bash
pip install -e .
```
此命令以可编辑模式安装软件包以及所有依赖项：
- `mcp>=1.0.0` – 模型上下文协议
- `httpx>=0.27.0` – 异步 HTTP 客户端
- `tenacity>=9.0.0` – 重试库
- `pydantic>=2.7.0` – 数据验证
- `pydantic-settings>=2.3.0` – 配置管理
- `python-dotenv>=1.0.0` – 环境变量加载
---
## 🔧 贡献
欢迎贡献！请提交拉取请求到主分支。
---
## 📝 许可证
本项目根据 [MIT 许可证](https://opensource.org/licenses/MIT) 的条款许可。
---
## 📅 路线图
请参阅 [项目路线图](https://github.com/sudhanshu-singh22/ServiceNow_MCP/issues?q=is%3Apr+is%3Aopen+label%3Aenhancement) 以获取即将推出的功能。
---
## 🤝 致谢
感谢所有贡献者！
---
## 📝 版权
2024 ServiceNow MCP 服务器。保留所有权利。
### Claude 代码集成
1. **在项目根目录中创建或更新 `.mcp.json`：**
```json
{
"mcpServers": {
"servicenow": {
"command": "python",
"args": ["-m", "servicenow_mcp.server"],
"cwd": "/path/to/servicenow-mcp",
"env": {
"SERVICENOW_INSTANCE_URL": "https://your-instance.service-now.com",
"SERVICENOW_AUTH_METHOD": "oauth",
"SERVICENOW_OAUTH_CLIENT_ID": "your-client-id",
"SERVICENOW_OAUTH_CLIENT_SECRET": "your-client-secret",
"SERVICENOW_OAUTH_TOKEN_URL": "https://your-instance.service-now.com/oauth_token.do"
}
}
}
}
```
2. **重新加载 Claude 代码**
### 自定义 MCP 客户端
对于自定义客户端，请使用 stdio 协议：
```python
import subprocess
import json
# 启动 MCP 服务器
proc = subprocess.Popen(
["python", "-m", "servicenow_mcp.server"],
stdin=subprocess.PIPE,
stdout=subprocess.PIPE,
stderr=subprocess.PIPE,
cwd="/path/to/servicenow-mcp",
env={
**os.environ,
"SERVICENOW_INSTANCE_URL": "https://your-instance.service-now.com",
"SERVICENOW_AUTH_METHOD": "bearer",
"SERVICENOW_BEARER_TOKEN": "your-token",
}
)
# 通过 stdin/stdout 发送 MCP 消息，遵循 MCP 协议规范
```
---
## 🛠️ 可用工具
### 📊 表格管理（2 个工具）
#### `create_table`
创建自定义应用程序表格。
**参数：**
```json
{
"label": "string", // 可读的表格名称（必填）
"name": "string", // 表格名称，以 u_ 为前缀（必填）
"extends": "string", // 父表格（默认：task）
"access": "string", // "public" 或 "protected"（默认：public）
"create_module": "boolean" // 自动创建导航模块（默认：false）
}
```
**示例：**
```json
{
"label": "员工入职",
"name": "u_employee_onboarding",
"extends": "task",
"access": "public",
"create_module": true
}
```
#### `list_tables`
列出实例中的所有表格。
**参数：**
```json
{
"search_term": "string", // 可选筛选条件（不区分大小写）
"limit": "integer" // 最大结果数（默认：100）
}
```
---
### 🔑 字段 / 词典（2 个工具）
#### `create_field`
向表格添加新列/字段。
**参数：**
```json
{
"table_name": "string", // 目标表格（必填）
"column_label": "string", // 用户友好名称（必填）
"column_name": "string", // 技术名称（必填）
"field_type": "string", // 字段类型（必填）
"reference_table": "string", // 参考字段
"active": "boolean", // 启用字段（默认：true）
"mandatory": "boolean", // 要求字段（默认：false）
"max_length": "integer" // 字符串字段
}
```
**字段类型：** `string`, `text`, `number`, `date`, `reference`, `boolean`, `choice`, `json`
#### `read_dictionary`
从表格词典中读取字段定义。
**参数：**
```json
{
"table_name": "string", // 目标表格（必填）
"include_columns": "string", // 要检索的字段名称（可选）
"active_only": "boolean" // 仅限活动字段（默认：true）
}
```
---
### 📝 GlideRecord 查询（4 个工具）
#### `query_records`
使用编码查询语法查询表格中的记录。
**参数：**
```json
{
"table": "string", // 表格名称（必填）
"encoded_query": "string", // 编码查询（例如："active=true^priority=1"）
"fields": ["string"], // 要检索的列
"limit": "integer", // 最大记录数（默认：100）
"offset": "integer", // 分页偏移量（默认：0）
"order_by": "string", // 要排序的列
"order_by_desc": "string" // 要降序排列的列
}
```
**查询语法示例：**
- `active=true` – 活动字段等于 true
- `priority=1^priority=2` – OR 条件
- `nameLIKE%John%` – LIKE 模式匹配
- `created_on>2026-06-01` – 日期比较
#### `get_record`
通过 sys_id 获取单个记录。
**参数：**
```json
{
"table": "string", // 表格名称（必填）
"sys_id": "string", // 记录 ID（必填）
"fields": ["string"] // 要检索的列（可选）
}
```
#### `update_record`
更新现有记录。
**参数：**
```json
{
"table": "string", // 表格名称（必填）
"sys_id": "string", // 记录 ID（必填）
"updates": { // 字段更新（必填）
"field_name": "value"
}
}
```
#### `delete_record`
删除记录。
**参数：**
```json
{
"table": "string", // 表格名称（必填）
"sys_id": "string" // 记录 ID（必填）
}
```
---
### ⚙️ 业务规则（2 个工具）
#### `create_business_rule`
创建服务器端业务规则。
**参数：**
```json
{
"name": "string", // 规则名称（必填）
"table": "string", // 表格名称（必填）
"when": "string", // "before" 或 "after"（默认：before）
"on_insert": "boolean", // 触发插入（默认：true）
"on_update": "boolean", // 触发更新（默认：true）
"on_delete": "boolean", // 触发删除（默认：false）
"script": "string", // GlideScript 代码（必填）
"active": "boolean", // 启用规则（默认：true）
"description": "string" // 可选描述
}
```
#### `list_business_rules`
列出表格的业务规则。
**参数：**
```json
{
"table": "string", // 表格名称（必填）
"active_only": "boolean" // 仅限活动规则（默认：true）
}
```
---
### 📚 脚本包含（2 个工具）
#### `create_script_include`
创建可重用的服务器端库/包含。
**参数：**
```json
{
"name": "string", // 包含名称（必填）
"description": "string", // 可选描述
"use_class_template": "boolean", // 使用类模板（默认：true）
"client_callable": "boolean", // 可从客户端调用（默认：false）
"active": "boolean", // 启用包含（默认：true）
"script": "string" // 可选初始脚本
}
```
#### `list_script_includes`
列出实例中的脚本包含。
**参数：**
```json
{
"search_term": "string", // 可选筛选条件
"active_only": "boolean", // 仅限活动包含（默认：true）
"limit": "integer" // 最大结果数（默认：100）
}
```
---
### 🔐 访问控制列表（2 个工具）
#### `create_acl`
创建访问控制规则。
**参数：**
```json
{
"operation": "string", // "create", "read", "write", "delete"（必填）
"table_name": "string", // 表格名称（必填）
"roles": ["string"], // 适用角色
"script": "string", // 可选 GlideScript 条件
"description": "string", // 可选描述
"active": "boolean" // 启用 ACL（默认：true）
}
```
#### `list_acls`
列出访问控制规则。
**参数：**
```json
{
"table_name": "string", // 按表格筛选（可选）
"operation": "string", // 按操作筛选（可选）
"active_only": "boolean" // 仅限活动 ACL（默认：true）
}
```
---
### 🔄 Flow Designer（3 个工具）
#### `trigger_flow`
触发 Flow Designer 流。
**参数：**
```json
{
"flow_id": "string", // 流 ID（例如："global.flow_name"）（必填）
"inputs": { // 流输入变量
"key": "value"
},
"wait_for_completion": "boolean" // 等待完成（默认：false）
}
```
#### `get_flow_execution_status`
获取流执行的狀態。
**参数：**
```json
{
"execution_id": "string" // 执行 ID（必填）
}
```
#### `list_flows`
列出可用流。
**参数：**
```json
{
"search_term": "string", // 可选筛选条件
"active_only": "boolean", // 仅限活动流（默认：true）
"limit": "integer" // 最大结果数（默认：100）
}
```
---
### 📥 导入集（3 个工具）
#### `create_import_set_table`
创建导入集暂存表格。
**参数：**
```json
{
"name": "string", // 表格名称（必填）
"label": "string", // 显示标签
"target_table": "string" // 目标导入表格
}
```
#### `run_import_set`
将记录加载到导入集并可选地运行转换。
**参数：**
```json
{
"staging_table": "string", // 暂存表格名称（必填）
"records": [{"field": "value"}], // 要导入的记录（必填）
"transform_map_sys_id": "string", // 转换映射 ID（可选）
"run_transform": "boolean" // 执行转换（默认：false）
}
```
#### `list_transform_maps`
列出可用的转换映射。
**参数：**
```json
{
"search_term": "string", // 可选筛选条件
"limit": "integer" // 最大结果数（默认：100）
}
```
---
### 🌐 Scripted REST APIs（3 个工具）
#### `call_scripted_rest_api`
调用自定义 Scripted REST API 端点。
**参数：**
```json
{
"api_namespace": "string", // API 命名空间（必填）
"api_id": "string", // API ID（必填）
"resource_path": "string", // 可选资源路径
"method": "string", // HTTP 方法：GET, POST, PUT, DELETE
"query_params": { // 可选查询参数
"key": "value"
},
"body": {} // 可选请求体（适用于 POST/PUT）
}
```
#### `list_scripted_rest_apis`
列出可用的 Scripted REST APIs。
**参数：**
```json
{
"search_term": "string", // 可选筛选条件
"active_only": "boolean", // 仅限活动 API（默认：true）
"limit": "integer" // 最大结果数（默认：100）
}
```
#### `get_scripted_rest_resources`
获取特定 Scripted REST API 的资源。
**参数：**
```json
{
"api_id": "string" // API ID（必填）
}
```
---
## 📂 文件夹结构
```
servicenow-mcp/
│
├── .env.example # 环境变量模板
├── .gitignore # Git 忽略规则
├── pyproject.toml # Python 项目元数据和依赖项
├── README.md # 此文件
│
└── src/
└── servicenow_mcp/
├── __init__.py # 包初始化
├── server.py # MCP 服务器和工具注册（108KB）
│ # 包含所有 21 个工具定义
│
├── config.py # 配置管理
│ # - Pydantic 设置
│ # - 身份验证方法验证
│ # - 环境变量加载
│
├── client.py # 异步 HTTP 客户端
│ # - ServiceNowClient 类
│ # - OAuth令牌缓存
│ # - Tenacity 重试逻辑
│ # - 身份验证头注入
│
├── logger.py # 结构化日志配置
│ # - JSON 格式日志
│ # - stderr 输出
│
└── tools/ # （模块化工具 - 目前在 server.py 中）
├── __init__.py
├── tables.py # 表格管理工具
├── fields.py # 字段/词典工具
├── glide_record.py # GlideRecord 查询工具
├── business_rules.py # 业务规则工具
├── script_includes.py # 脚本包含工具
├── acls.py # 访问控制列表工具
├── flow_designer.py # Flow Designer 工具
├── import_sets.py # 导入集工具
└── scripted_rest.py # REST API 工具
```
### 关键文件说明
| 文件 | 大小 | 目的 |
|---|---|---|
| `server.py` | ~108 KB | MCP 服务器入口点，所有 21 个工具在此定义，SSE 消息处理 |
| `config.py` | ~4.8 KB | Pydantic 配置，对 4 种身份验证方法进行验证 |
| `client.py` | ~10.7 KB | 异步 HTTP 客户端，带有重试逻辑、身份验证注入、令牌缓存 |
| `logger.py` | ~1.3 KB | 结构化日志设置 |
| `pyproject.toml` | ~0.8 KB | 包元数据、依赖项、构建配置 |
---
## 🔒 安全考虑
### 身份验证最佳实践
#### 1. **从不提交机密信息**
```bash
# ❌ 差劲 - 机密信息在 .env 文件中
SERVICENOW_PASSWORD=SuperSecretPassword123
# ✓ 好 - 使用 .gitignore
# .gitignore
.env
.env.local
.env.*.local
```
#### 2. **在生产环境中使用 OAuth**
```env
# ✓ 生产环境 - OAuth 2.0
SERVICENOW_AUTH_METHOD=oauth
SERVICENOW_OAUTH_CLIENT_ID=${CLIENT_ID} # 在 CI/CD 中设置
SERVICENOW_OAUTH_CLIENT_SECRET=${CLIENT_SECRET} # 在 CI/CD 中设置
```
#### 3. **定期轮换凭证**
- 每 90 天更改基本身份验证密码
- 每年轮换 OAuth 客户端密钥
- 立即撤销未使用的 API 密钥
#### 4. **最小权限原则```
```
# 创建一个具有最小权限的 ServiceNow 用户
ServiceNow Admin > 用户管理 > 用户
Name: mcp_automation
Active: ✓
Roles: custom_mcp_role (最小所需权限)
# 定义自定义角色并赋予必要的权限
```
### 传输安全
#### **仅限 HTTPS**
所有与 ServiceNow 的通信必须使用 HTTPS:
```env
# ✓ 正确
SERVICENOW_INSTANCE_URL=https://dev12345.service-now.com
# ❌ 错误 - 永远不要使用 HTTP
SERVICENOW_INSTANCE_URL=http://dev12345.service-now.com
```
#### **TLS 证书验证**
客户端默认验证 TLS 证书。禁用（不推荐）：
```python
# client.py – 不推荐用于生产环境
client = httpx.AsyncClient(verify=False) # ⚠️ 安全风险
```
### 速率限制和限流
客户端包含自动重试逻辑以应对速率限制:
```env
SERVICENOW_MAX_RETRIES=5 # 更多重试次数（默认：3）
SERVICENOW_TIMEOUT_SECONDS=60 # 更长的超时时间（默认：30）
###
### 日志安全
#### **永远不要记录密码或机密信息**
```python
# ✓ 好 - 在日志中删除机密信息
log.info(f"身份验证方法: {method}, 用户: {user}, 密码: ***隐藏***")
# ❌ 差劲 - 记录凭证
log.debug(f"身份验证: {username}:{password}")
```
**配置日志级别：
```env
# 生产环境 - 最少日志记录
LOG_LEVEL=INFO
# 开发环境 - 详细日志记录
LOG_LEVEL=DEBUG
```
### 网络隔离
为了最大限度地提高安全性，请部署 MCP 服务器：
1. **防火墙** - 仅限出站连接限制到 ServiceNow 实例
2. **私有网络** - 不直接暴露给互联网
3. **VPN** - 访问远程实例
4. **容器** - 使用 Docker 并使用网络策略
### 监控和审计
启用 ServiceNow 审计日志以跟踪所有 API 调用:
```
ServiceNow Admin > 系统审计 > 审计日志
过滤条件: Made By = mcp_automation_user
排序: 时间戳 DESC
```
---
## 🛠️ 开发环境配置
### 前置条件
- Python 3.11+
- Git
- VS Code 或 PyCharm（推荐）
### 设置开发环境
```bash
# 1. 克隆仓库
git clone https://github.com/sudhanshu-singh22/ServiceNow_MCP.git
| File | 大小 | 目的 |
|---|---|---|
| `server.py` | ~108 KB | MCP 服务器入口点，所有 21 个工具在此定义，SSE 消息处理 |
| `config.py` | ~4.8 KB | Pydantic 配置，对 4 种身份验证方法进行验证 |
| `client.py` | ~10.7 KB | 异步 HTTP 客户端，带有重试逻辑、身份验证注入、令牌缓存 |
| `logger.py` | ~1.3 KB | 结构化日志设置 |
| `pyproject.toml` | ~0.8 KB | 包元数据、依赖项、构建配置 |
---
## 🔒 安全注意事项
### 身份验证最佳实践
#### 1. **绝不提交机密信息**
```bash
# ❌ 差劲 - 机密信息在 .env 文件中
SERVICENOW_PASSWORD=SuperSecretPassword123
# ✓ 好 - 使用 .gitignore
# .gitignore
.env
.env.local
.env.*.local
```
#### 知识共享许可协议
### 新增工具
要向MCP服务器添加新工具：
1. **在 `server.py` 中定义工具：**
```python
@server.call_tool()
async def handle_my_tool(arguments: dict[str, Any]) -> list[types.TextContent]:
"""
我的新工具描述。
参数：
arguments: 工具参数
"""
try:
# 验证输入
param1 = arguments.get("param1")
if not param1:
raise ValueError("param1 是必需的")
# 执行工具逻辑
async with ServiceNowClient() as sn:
result = await sn.some_operation(param1)
return [types.TextContent(type="text", text=json.dumps(result))]
except Exception as e:
error_msg = format_error(e)
return [types.TextContent(type="text", text=f"错误：{error_msg}")]
```
2. **更新 README 中的工具数量**
3. **在 `tests/test_tools.py` 中添加测试**
4. **在 README 中记录工具**
### 调试
启用调试日志：
```bash
LOG_LEVEL=DEBUG servicenow-mcp
```
查看MCP服务器日志（写入stderr）：
```bash
servicenow-mcp 2>&1 | tee server.log
```
使用调试器连接：
```bash
# 使用 debugpy
python -m debugpy --listen 5678 -m servicenow_mcp.server
```
---
## 🤝 贡献
我们欢迎贡献！请遵循以下指南：
### 行为准则
尊重和包容。本项目遵守贡献者契约。
### 如何贡献
1. **在 GitHub 上 fork 仓库**
2. **创建功能分支：**
```bash
git checkout -b feature/amazing-feature
```
3. **进行更改并附上清晰的提交消息**
4. **为新功能添加测试**
5. **确保所有测试通过：**
```bash
pytest
```
6. **格式化代码：**
```bash
ruff format .
ruff check . --fix
```
7. **推送到您的 fork：**
```bash
git push origin feature/amazing-feature
```
8. **创建带有清晰描述的拉取请求**
### 拉取请求要求
- ✅ 测试通过 (`pytest`)
- ✅ 代码已格式化 (`ruff format`)
- ✅ Linting 通过 (`ruff check`)
- ✅ 类型提示正确 (`mypy`)
- ✅ 文档已更新
- ✅ 变更日志已更新
### 报告问题
报告错误时，请包括：
- **Python 版本** (`python --version`)
- **操作系统** （Windows/macOS/Linux）
- **错误消息** 和堆栈跟踪
- **重现步骤**
- **预期与实际行为**
- **.env 配置** （请隐藏密钥！）
问题模板示例：
```markdown
## 错误报告
**描述：**
问题的简要描述
**重现步骤：**
1. 使用 [身份验证方法] 设置
2. 使用 [参数] 调用 [工具名称]
3. 出现错误
**错误消息：**
```
[在此粘贴错误和堆栈跟踪]
```
**环境：**
- Python：3.11.0
- 操作系统：macOS 13.2
- 身份验证方法：oauth
```
---
## 🗺️ 路线图
### ✅ v1.0（当前）
- [x] 21个核心工具用于表格/记录/流程管理
- [x] 4种身份验证方法
- [x] 具有指数退避的重试逻辑
- [x] 结构化日志记录
- [x] MCP协议支持
### 🚀 v1.1（计划中）
- [ ] 服务目录工具
- [ ] 变更管理工具
- [ ] 事件/问题管理工具
- [ ] CMDB集成
- [ ] 高级查询构建器
### 📋 v1.2+（未来）
- [ ] Webhook支持
- [ ] GraphQL查询支持
- [ ] WebSocket流媒体
- [ ] 批量操作优化
- [ ] 缓存层
- [ ] 自定义工具框架
- [ ] 插件系统
### 🎯 长期愿景
- 多实例支持
- 分布式/联邦MCP服务器
- 零信任身份验证
- AI辅助查询生成
- 自然语言到GlideScript翻译
---
## 📄 许可证
该项目根据 **MIT许可证** 授权 – 有关详细信息，请参阅 [LICENSE](LICENSE) 文件。
### 摘要
✓ **免费用于商业用途**
✓ **允许修改**
✓ **允许分发**
✓ **允许私人使用**
✗ **责任：** 按原样提供，不提供担保
✗ **商标权：** 不包括
---
## 📞 支持与社区
- **GitHub 问题：** [报告错误或请求功能](https://github.com/sudhanshu-singh22/ServiceNow_MCP/issues)
- **讨论：** [提问和分享想法](https://github.com/sudhanshu-singh22/ServiceNow_MCP/discussions)
- **文档：** 在此README中阅读完整文档
---
## 🙏 致谢
- [模型上下文协议](https://modelcontextprotocol.io/) – MCP规范
- [Anthropic Claude](https://claude.ai/) – AI代理技术
- [ServiceNow开发者社区](https://developer.servicenow.com/)
- 所有提供反馈的贡献者和用户
---
## 🎬 快速入门检查清单
- [ ] 克隆仓库
- [ ] 创建虚拟环境
- [ ] 安装软件包 (`pip install -e .`)
- [ ] 创建 `.env` 文件
- [ ] 配置身份验证
- [ ] 运行服务器 (`servicenow-mcp`)
- [ ] 配置MCP客户端（Claude Desktop / Code）
- [ ] 使用第一个提示进行测试
- [ ] 阅读安全注意事项
- [ ] 为贡献设置开发环境
---
**由ServiceNow开发者为ServiceNow开发者制作 ❤️**
*最后更新：2026-06-04*
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器