Gysosin MCP

ServiceNow MCP服务器

ServiceNow MCP Server实现了模型上下文协议（MCP），因此Claude和其他兼容MCP的客户端可以安全地与ServiceNow实例交互。服务器将来自客户端的工具调用转换为ServiceNow REST API请求，并返回易于语言模型使用的结构化结果。

亮点

• 多个身份验证流：基本身份验证、OAuth和API密钥交换
• 用于事件、目录项、工作流、变更集、知识和敏捷工作的丰富工具目录
• 通过以角色为中心的包进行选择性工具加载，以保持在模型限制范围内
• 支持标准输入/输出传输和流式HTTP端点
• 附带可运行的示例、脚本设置帮助程序和自动pytest套件

仓库的规划

• src/servicenow_mcp/ 核心服务器实现、CLI入口点、工具定义和实用程序
• config/tool_packages.yaml 默认的基于角色的工具包，可以为您的组织进行调整
• docs/ 对目录、工作流程、变更和用户管理进行深入探讨和操作指导
• examples/ 演示常见流和集成模式的可运行脚本
• scripts/ 用于配置凭据、检查实例状态和其他本地任务的辅助命令
• tests/ 关键工具、资源和传输的pytest覆盖率

入门指南

需求

• Python 3.11+
• 具有您计划公开的工具所需权限的ServiceNow实例凭据

克隆并安装

git clone https://github.com/gysosin/servicenow-mcp-http.git
cd servicenow-mcp-http
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e .

复制示例环境文件并填写占位符：

cp .env.example .env

配置

核心环境变量

• SERVICENOW_INSTANCE_URL 例如 https://your-instance.service-now.com
• SERVICENOW_AUTH_TYPE 之一 basic, oauth，或 api_key
• SERVICENOW_USERNAME 和 SERVICENOW_PASSWORD 用于基本身份验证
• SERVICENOW_API_KEY 使用API密钥流时
• SERVICENOW_CLIENT_ID, SERVICENOW_CLIENT_SECRET，以及 SERVICENOW_TOKEN_URL 对于OAuth
• SERVICENOW_HTTP_HOST, SERVICENOW_HTTP_PORT，以及 SERVICENOW_HTTP_BASE_PATH 调整可选的HTTP传输

所有环境变量都可以添加到 .env 地方发展档案；CLI会自动加载该文件。

运行服务器

标准MCP（stdio）传输

直接从Python或安装的控制台脚本启动服务器：

python -m servicenow_mcp.cli
# or
servicenow-mcp

如果您不想使用内联传递凭据 .env 文件：

SERVICENOW_INSTANCE_URL=https://your-instance.service-now.com \
SERVICENOW_USERNAME=your-username \
SERVICENOW_PASSWORD=your-password \
SERVICENOW_AUTH_TYPE=basic \
servicenow-mcp

可流式HTTP传输

通过HTTP向使用MCP Streamable规范的客户端公开服务器：

servicenow-mcp-sse --instance-url https://your-instance.service-now.com \
  --auth-type basic --username your-username --password your-password \
  --host 0.0.0.0 --port 8080

HTTP应用程序公开 POST /mcp 用于JSON-RPC消息和 GET /mcp 对于事件流。使用以下参数调整基础路径 SERVICENOW_HTTP_BASE_PATH 如果您需要从不同的路由为API提供服务。

工具包

服务器可以通过设置来限制注册哪些工具 MCP_TOOL_PACKAGE。包定义见 config/tool_packages.yaml 并且可以根据您的部署进行定制。有用的默认值包括：

• service_desk 事件、用户查找和知识检索
• catalog_builder 目录项、类别、变量和优化助手
• change_coordinator 变更请求、批准和相关任务
• knowledge_author 知识库、类别和文章生命周期管理
• platform_developer 脚本包括工作流和变更集操作
• system_administrator 用户和组管理以及syslog访问
• agile_management 史诗、故事、scrum任务和项目资源
• full 启用每个工具（默认）
• none 禁用除自省助手之外的所有工具

每次运行切换包：

export MCP_TOOL_PACKAGE=catalog_builder
servicenow-mcp

这 list_tool_packages 工具始终可用（除非 none 选择）以报告哪个包处于活动状态。

示例和文件

• 浏览 examples/ 用于执行目录优化、变更管理、工作流自动化等的脚本目录。
• 这 docs/ 文件夹包含目录、更改、工作流、知识和用户管理功能的详细指南。
• debug_workflow_api.py 和 examples/debug_workflow_api.py 展示如何交互式地反思工作流定义。

开发流程

pip install -e .[dev]
pytest
ruff check src tests
black src tests

使用中的脚本 scripts/ 在运行服务器之前，验证ServiceNow凭据并唤醒开发人员实例。

故障排除

• argument after ** must be a mapping：传递字典以更改管理助手，而不是Pydantic模型；帮助程序尝试自动解包无效输入。
• Missing required parameter 'type'：确保必填的ServiceNow字段（例如 short_description 和 type 创建更改请求时）。
• Invalid value for parameter 'type'：使用已接受的ServiceNow枚举(normal, standard, emergency等等）。
• Cannot find get_headers method：确认工具参数以正确的顺序提供，以便首先传递身份验证管理器。

贡献

欢迎拉取请求。请分叉存储库，创建一个功能分支，并在本地测试通过后打开PR。

许可证

根据MIT许可证发布。看 LICENSE 了解详情。