AI导哈

服务Now MCP协议服务器

一个Go语言实现的ServiceNow MCP协议服务器，使AI助手能够通过标准化协议与ServiceNow实例交互。

  • by JeremyProffittOrg
  • Go
  • 本地部署
  • 更新于
在 GitHub 查看 JeremyProffitt/go-mcp-servicenow

使用说明

立即访问mcp服务

ServiceNow的模型上下文协议（MCP）服务器的Go实现。该服务器使AI助手能够通过标准化协议与ServiceNow实例进行交互。

特性

  • 完全支持MCP协议：基于JSON-RPC 2.0的通信
  • 多种身份验证方法：基本身份验证、OAuth 2.0、API密钥
  • 全面的ServiceNow覆盖：跨多个领域的70多种工具
  • 双服务器模式：Stdio（用于本地）和HTTP（用于远程/容器化）
  • 只读模式：写入操作的可选限制
  • 速率限制：内置保护（每20秒5次通话）

ServiceNow概念

了解这些核心的ServiceNow概念将帮助您有效地使用此MCP服务器：

sys_id

ServiceNow中的每条记录都有一个唯一的32个字符的十六进制标识符，称为 sys_id。这是所有记录的主键。

  • 格式：32个十六进制字符（例如。， a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6)
  • 用法：大多数工具接受sys_id或人类可读标识符（如INC0010001）
  • 示例：何时 get_incident 回报 sys_id: "6816f79cc0a8016401c5a33be04be441"，使用此值进行更新

显示值vs值

ServiceNow引用字段可以返回原始值或人类可读的显示值：

  • 价值：引用记录的sys_id
  • 显示值：人类可读的文本（例如，用户的全名而不是sys_id）
  • 此服务器返回 display_value 默认情况下，为了可读性

编码查询语法

许多列表工具支持ServiceNow的编码查询语法进行高级过滤：

运算符 含义 示例
= 等于 state=1
!= 不等于 state!=7
^ 以及 state=1^priority=2
^OR 或 state=1^ORstate=2
LIKE 包含 short_descriptionLIKEnetwork
STARTSWITH 开始于 numberSTARTSWITHINC
> 大于 priority>2
< 小于 sys_created_on<2024-01-01
ORDERBY 升序排序 ORDERBYsys_created_on
ORDERBYDESC 降序排序 ORDERBYDESCpriority

示例：查找高优先级未解决事件： state=1^priority<=2^ORDERBYDESCsys_created_on

参数格式

记录标识符

大多数工具接受多种标识符格式：

类型 数字格式 sys_id格式
事故 INC0010001 a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
变更请求 CHG0010001 32个字符的十六进制字符串
知识文章 KB0010001 32个字符的十六进制字符串
用户 admin （用户名）或 admin@example.com （电子邮件） 32个字符的十六进制字符串

国家价值观

不同的记录类型使用不同的状态代码：

事件:

  • 1 新
  • 2 =进行中
  • 3 =暂停
  • 6 =已解决
  • 7 =关闭
  • 8 =已取消

变更请求:

  • -5 新
  • -4 =评估
  • -3 =授权
  • -2 =预定
  • -1 =实施
  • 0 =审核
  • 3 =关闭
  • 4 =已取消

优先级和影响值

价值 优先级 影响/紧迫性
1 严重 高
2 高 中
3 中等 低
4 低 -
5 规划 -

日期/时间格式

使用ISO 8601格式： YYYY-MM-DD HH:MM:SS

例子： 2024-12-15 14:30:00

工具参考

事件管理

工具 说明 关键参数
list_incidents 列出带有过滤功能的事件 limit, state, assigned_to, category, query
get_incident 获取事件详细信息 incident_id （编号或sys_id）
create_incident 创建新事件 short_description （必填）， priority, category
update_incident 更新现有事件 incident_id，要更新的字段
add_incident_comment 添加评论/工作注释 incident_id, comment, is_work_note
resolve_incident 解决事件 incident_id, resolution_code, resolution_notes

变更管理

工具 说明 关键参数
list_change_requests 列表更改与筛选 limit, state, type, assigned_to
get_change_request 获取更改详细信息 change_id （编号或sys_id）
create_change_request 创建新更改 short_description, type （正常/标准/紧急）
update_change_request 更新现有更改 change_id，要更新的字段
add_change_task 添加要更改的任务 change_id, short_description
submit_change_for_approval 提交审批 change_id
approve_change 批准待定变更 change_id, comments
reject_change 拒绝待处理的更改 change_id, reason

服务目录

工具 说明 关键参数
list_catalogs 列出服务目录 limit
list_catalog_items 列出可订购项目 limit, category, query
get_catalog_item 获取商品详细信息 item_id
list_catalog_categories 列出类别 catalog_id, parent_id
list_catalog_item_variables 列出表单变量 item_id
create_catalog_category 创建类别 title, catalog_id
update_catalog_category 更新类别 category_id，要更新的字段
update_catalog_item 更新项目 item_id，要更新的字段
create_catalog_item_variable 创建表单字段 item_id, name, question_text, type
move_catalog_items 将项目移动到类别 item_ids, target_category_id

知识库

工具 说明 关键参数
list_knowledge_bases 列出知识库 limit, active
list_knowledge_articles 列出文章 limit, knowledge_base, category, query
get_knowledge_article 获取文章详细信息 article_id （编号或sys_id）
list_kb_categories 列出KB类别 knowledge_base, parent
create_knowledge_base 创建KB title, description
create_kb_category 创建类别 label, knowledge_base
create_knowledge_article 创建文章 short_description, text, knowledge_base
update_knowledge_article 更新文章 article_id，要更新的字段
publish_knowledge_article 发表文章 article_id

用户和组

工具 说明 关键参数
list_users 列出具有筛选功能的用户 limit, active, department, query
get_user 获取用户详细信息 user_id （sys_id、用户名或电子邮件）
list_groups 列出组 limit, active, query
create_user 创建用户 user_name, first_name, last_name, email
update_user 更新用户 user_id，要更新的字段
create_group 创建组 name, description
update_group 更新组 group_id，要更新的字段
add_group_members 将用户添加到组 group_id, user_ids
remove_group_members 从组中删除用户 group_id, user_ids

工作流

工具 说明 关键参数
list_workflows 列出工作流 limit, active, table
get_workflow 获取工作流详细信息 workflow_id （sys_id或名称）
create_workflow 创建工作流 name, table
update_workflow 更新工作流程 workflow_id，要更新的字段
delete_workflow 删除工作流 workflow_id

脚本包括

工具 说明 关键参数
list_script_includes 列表脚本包括 limit, active, query
get_script_include 获取脚本详细信息 script_id （sys_id或名称）
create_script_include 创建脚本 name, api_name, script
update_script_include 更新脚本 script_id，要更新的字段
delete_script_include 删除脚本 script_id

变更集（更新集）

工具 说明 关键参数
list_changesets 列出更新集 limit, state, created_by
get_changeset 获取变更集详细信息 changeset_id （sys_id或名称）
create_changeset 创建更新集 name, description
update_changeset 更新变更集 changeset_id，要更新的字段
commit_changeset 标记为完成 changeset_id

敏捷开发

工具 说明 关键参数
list_stories 列出用户故事 limit, state, sprint, assigned_to
list_epics 列出史诗 limit, state, product
list_scrum_tasks 列出scrum任务 limit, story, state, assigned_to
list_projects 列出项目 limit, state, active
create_story 创建用户故事 short_description, story_points, sprint
update_story 更新故事 story_id，要更新的字段
create_epic 创造史诗 short_description, product
update_epic 更新史诗 epic_id，要更新的字段
create_scrum_task 创建任务 short_description, story, type
update_scrum_task 更新任务 task_id，要更新的字段
create_project 创建项目 short_description, start_date, end_date
update_project 更新项目 project_id，要更新的字段

常见工作流

事件生命周期

  1. 创建偶发事件: create_incident 随着 short_description 和 category
  2. 分配给组/用户: update_incident 随着 assignment_group 或 assigned_to
  3. 添加工作笔记: add_incident_comment 随着 is_work_note: true
  4. 更新进度: update_incident 随着 state: "2" （进行中）
  5. 解决: resolve_incident 随着 resolution_code 和 resolution_notes

变更请求流程

  1. 创建更改: create_change_request 随着 type （正常/标准/紧急）
  2. 添加任务: add_change_task 对于每个实施步骤
  3. 提交审批: submit_change_for_approval
  4. 批准/拒绝: approve_change 或 reject_change
  5. 跟踪进度: update_change_request 状态更新

知识文章发布

  1. 创建文章: create_knowledge_article （创建于草稿状态）
  2. 更新内容: update_knowledge_article 精炼
  3. 发布: publish_knowledge_article 使可见

用户入职培训

  1. 创建用户: create_user 带有必填字段
  2. 查找组: list_groups 识别相关群体
  3. 添加到组: add_group_members 对于每个组

安装

从源代码构建

git clone https://github.com/elastiflow/go-mcp-servicenow.git
cd go-mcp-servicenow
go build -o go-mcp-servicenow .

码头工人

docker build -t go-mcp-servicenow .

配置

环境变量

变量 描述 必填
SERVICENOW_INSTANCE_URL ServiceNow实例URL（例如。，https://dev12345.service-now.com) 是
SERVICENOW_AUTH_TYPE 身份验证类型： basic, oauth，或 api_key 是的
SERVICENOW_USERNAME 基本/oauth身份验证用户名 基本/outh身份验证用户名
SERVICENOW_PASSWORD 基本/oauth身份验证密码 基本/outh身份验证密码
SERVICENOW_CLIENT_ID OAuth客户端ID 用于OAuth
SERVICENOW_CLIENT_SECRET OAuth客户端机密 用于OAuth
SERVICENOW_API_KEY API_key auth的API密钥 用于API_key
READ_ONLY_MODE 设置为 true 禁用写入操作 否
MCP_AUTH_TOKEN HTTP模式身份验证令牌 否
MCP_LOG_DIR 日志文件目录 否
MCP_LOG_LEVEL 日志级别：调试、信息、警告、错误 否

身份验证类型

基本身份验证

export SERVICENOW_INSTANCE_URL="https://dev12345.service-now.com"
export SERVICENOW_AUTH_TYPE="basic"
export SERVICENOW_USERNAME="admin"
export SERVICENOW_PASSWORD="password"

OAuth 2.0（客户端凭据）

export SERVICENOW_INSTANCE_URL="https://dev12345.service-now.com"
export SERVICENOW_AUTH_TYPE="oauth"
export SERVICENOW_CLIENT_ID="your_client_id"
export SERVICENOW_CLIENT_SECRET="your_client_secret"

OAuth 2.0（密码授权）

export SERVICENOW_INSTANCE_URL="https://dev12345.service-now.com"
export SERVICENOW_AUTH_TYPE="oauth"
export SERVICENOW_CLIENT_ID="your_client_id"
export SERVICENOW_CLIENT_SECRET="your_client_secret"
export SERVICENOW_USERNAME="admin"
export SERVICENOW_PASSWORD="password"

API密钥

export SERVICENOW_INSTANCE_URL="https://dev12345.service-now.com"
export SERVICENOW_AUTH_TYPE="api_key"
export SERVICENOW_API_KEY="your_api_key"

用法

标准模式（默认）

./go-mcp-servicenow

HTTP模式

./go-mcp-servicenow --http --host 0.0.0.0 --port 3000

命令行选项

标志 描述 默认值
--http 在HTTP模式下运行 false
--host HTTP主机 127.0.0.1
--port HTTP端口 3000
--read-only 启用只读模式 false
--log-dir 日志目录 操作系统临时目录
--log-level 日志级别 信息
--version 显示版本 -

HTTP模式详细信息

在HTTP模式下运行时，服务器会公开：

  • POST / -MCP JSON-RPC端点
  • GET /health -健康检查端点（返回 {"status":"ok","version":"X.X.X"})

认证：HTTP模式需要 Authorization 所有请求的标头（除 /health).授权层是可插拔的；默认情况下，它接受任何令牌。

按请求凭据：在HTTP模式下，ServiceNow凭据可以通过标头而不是环境变量传递，从而启用多用户场景：

标题 描述
X-ServiceNow-Username ServiceNow用户名（覆盖 SERVICENOW_USERNAME)
X-ServiceNow-Password ServiceNow密码（覆盖 SERVICENOW_PASSWORD)
X-ServiceNow-API-Key ServiceNow API密钥（重写 SERVICENOW_API_KEY)

这些标头会覆盖相应的环境变量（如果存在）。

码头工人

docker run -p 3000:3000 \
  -e SERVICENOW_INSTANCE_URL="https://dev12345.service-now.com" \
  -e SERVICENOW_AUTH_TYPE="basic" \
  -e SERVICENOW_USERNAME="admin" \
  -e SERVICENOW_PASSWORD="password" \
  go-mcp-servicenow

Claude桌面集成

添加到您的Claude Desktop配置(claude_desktop_config.json):

{
  "mcpServers": {
    "servicenow": {
      "command": "/path/to/go-mcp-servicenow",
      "env": {
        "SERVICENOW_INSTANCE_URL": "https://dev12345.service-now.com",
        "SERVICENOW_AUTH_TYPE": "basic",
        "SERVICENOW_USERNAME": "admin",
        "SERVICENOW_PASSWORD": "password"
      }
    }
  }
}

API端点（HTTP模式）

端点 方法 描述
/ POST MCP JSON-RPC端点
/health GET 健康检查

错误处理

常见错误及解决方法：

错误 原因 解决方案
“超出速率限制” 请求太多 等待20秒，降低请求频率
“找不到记录” ID无效 验证记录号或sys_ID是否存在
“写入操作被阻止” 启用只读模式 删除 --read-only 旗帜或 READ_ONLY_MODE=true
“身份验证失败” 凭据无效 检查用户名/密码或令牌有效性
“拒绝访问” 权限不足 确保用户具有所需的ServiceNow角色

发展

项目结构

go-mcp-servicenow/
├── main.go
├── go.mod
├── Dockerfile
├── ecs-task-definition.json
├── README.md
└── pkg/
    ├── mcp/
    │   ├── server.go      # MCP server implementation
    │   └── types.go       # MCP protocol types
    ├── auth/
    │   └── auth.go        # MCP authentication
    ├── logging/
    │   └── logging.go     # Structured logging
    ├── servicenow/
    │   ├── client.go      # ServiceNow API client
    │   └── config.go      # Configuration handling
    └── tools/
        ├── registry.go    # Tool registration
        ├── helpers.go     # Utility functions
        ├── incidents.go   # Incident tools
        ├── catalog.go     # Catalog tools
        ├── change.go      # Change management tools
        ├── knowledge.go   # Knowledge base tools
        ├── users.go       # User/group tools
        ├── workflow.go    # Workflow tools
        ├── script_include.go  # Script include tools
        ├── changeset.go   # Changeset tools
        └── agile.go       # Agile tools

建筑

go build -o go-mcp-servicenow .

测试

go test ./...

许可证

MIT许可证

学分

搬运来的 梯队人工智能实验室/servicenow mcp python

相关 MCP