servicenow-mcp

一个轻量级的 MCP 服务器，让 AI 代理能够通过 Table API 创建、搜索和更新 ServiceNow 事件。基于官方 Python mcp 包（FastMCP 风格装饰器）、httpx 和 python-dotenv 构建。通过 stdio 运行。

所有代码都集中在一个文件中：server.py。

设置

需要 Python 3.12+ 和 uv。

uv sync

在 server.py 旁边创建一个 .env 文件（已被 git 忽略），其中包含你实例的基本认证凭据——使用 个人开发者实例 即可：

SNOW_INSTANCE_URL=https://devXXXXXX.service-now.com
SNOW_USERNAME=admin
SNOW_PASSWORD=your-password
# optional, default 15
SNOW_TIMEOUT_SECONDS=15

运行服务器（它通过 stdin/stdout 使用 MCP 协议通信，因此没有可见输出——必须由 MCP 客户端启动）：

uv run server.py

注册到 MCP 客户端

将客户端指向 uv 和项目目录，以便正确加载 .venv 和 .env：

{
  "mcpServers": {
    "servicenow": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/servicenow-mcp", "run", "server.py"]
    }
  }
}

对于 Claude Code：claude mcp add servicenow -- uv --directory /absolute/path/to/servicenow-mcp run server.py。

客户端环境中已设置的环境变量优先级高于 .env。

Related MCP server: sn-mcp-bridge

工具

所有工具在出错时都会返回可读的工具错误（以 isError 形式呈现给代理），而不是堆栈跟踪，例如：

• Authentication failed (401): check SNOW_USERNAME and SNOW_PASSWORD. ServiceNow said: User is not authenticated …

• Could not connect to https://…: [Errno 8] nodename nor servname provided … Check SNOW_INSTANCE_URL and your network connection.

• Timed out after 15s talking to https://… The instance may be hibernating (PDI) or unreachable.

• Incident 'INC9999999' was not found on https://….

• Forbidden (403): the user lacks permission … or the update was rejected by a business rule. ServiceNow said: … （例如，在未填写解决字段的情况下解决事件）。

设计说明

• ServiceNowClient 封装了一个 httpx.AsyncClient（基本认证、JSON 头、超时），并暴露了 create_record / query_records / get_record_by_number / update_record 方法。所有错误都被转换为带有可读消息的 ServiceNowError。

• 工具通过 get_client() 获取客户端；在测试中调用 set_client(fake) 即可替换为模拟对象，无需访问网络。

• 记录通过 sysparm_display_value=all 获取，因此状态/紧急程度标签来自实例本身，而非硬编码映射（友好名称别名仅用于输入）。

• mcp 2.x 将 FastMCP 重命名为 MCPServer；server.py 会导入存在的版本，因此可在 1.x 和 2.x 上运行。

冒烟测试

针对真实实例运行（会写入一个事件）：

uv run python -c "
import asyncio, server
async def main():
    c = await server.create_incident('MCP server smoke test', 'created by smoke test')
    print(c)
    print(await server.query_incidents(query_text='MCP server smoke test'))
    print(await server.update_incident(c['number'], work_notes='hello from MCP'))
asyncio.run(main())
"