PagerDuty MCP Server

PagerDuty MCP Server

一个向大模型提供 PagerDuty API 功能的服务。此服务旨在通过结构化输入和输出以编程方式使用。

概述

PagerDuty MCP 服务提供一组用于与 PagerDuty API 交互的工具。这些工具旨在供大模型使用，以便对 PagerDuty 资源（如事件、服务、团队和用户）执行各种操作。

开始使用

1. 初始化本地 Python 环境：

cd pagerduty-mcp-server
brew install uv
uv sync

2. 配置身份验证（参见下方的身份验证）。

身份验证

优先级：X-PagerDuty-Token HTTP 标头 > PAGERDUTY_API_TOKEN 环境变量 > OAuth 2.0 PKCE

选项 1：X-PagerDuty-Token 标头（平台集成）

作为会注入每个请求凭据的平台的一部分运行时，服务会读取 X-PagerDuty-Token HTTP 标头。此方式优先级最高，无需任何本地配置。

选项 2：API 令牌（推荐给大多数用户）

设置 PAGERDUTY_API_TOKEN 环境变量，或将其添加到项目根目录下的 .env 文件中。如果存在 .env 文件，服务会自动加载其中的环境变量。

环境变量：

export PAGERDUTY_API_TOKEN=your_api_token_here

.env 文件（推荐）：

echo "PAGERDUTY_API_TOKEN=your_api_token_here" > .env

选项 3：OAuth 2.0 PKCE（本地交互式使用）

OAuth 可用于本地独立使用。它会打开浏览器进行身份验证，并将令牌安全地存储在操作系统密钥环中。OAuth 需选择启用——仅当设置了 PAGERDUTY_CLIENT_ID 且不存在 API 令牌时才会启用。

设置：

1. 在 Integrations → Developer Tools → My Apps 中注册 PagerDuty OAuth 应用。
2. 将所需范围设置为 read write。
3. 将重定向 URI 设置为 http://localhost:5173/oauth/pagerduty（默认端口）。
4. 将 PAGERDUTY_CLIENT_ID 环境变量设置为应用的客户端 ID。

可选配置：

• 设置 PAGERDUTY_CLIENT_SECRET 以启用令牌刷新（机密客户端）。
• 设置 PAGERDUTY_OAUTH_CALLBACK_PORT 以覆盖默认回调端口（5173）。

使用方法

Claude/Cursor

{
  "mcpServers": {
    "pagerduty-mcp-server": {
      "command": "uvx",
      "args": ["pagerduty-mcp-server"],
      "env": {
          "PAGERDUTY_API_TOKEN": "<PAGERDUTY_API_TOKEN>"
      }
    }
  }
}

作为独立服务运行

uv run pagerduty-mcp-server

可用工具

读取工具

• get_escalation_policies — 列出升级策略或获取其详细信息
• get_incidents — 列出事件或获取其详细信息（支持按状态、紧急程度、服务、团队和时间范围筛选）
• get_oncalls — 列出指定时间范围内的值班条目
• get_schedules — 列出排班表或获取其详细信息
• get_services — 列出服务或获取其详细信息
• get_teams — 列出团队或获取其详细信息
• get_users — 列出用户或获取其详细信息
• list_users_oncall — 列出指定排班表中的值班用户
• build_user_context — 为当前经过身份验证的用户构建上下文对象

写入工具

• acknowledge_incident — 确认事件（表示正在积极调查）
• resolve_incident — 解决事件（停止进一步升级）
• add_incident_note — 为事件添加备注（用于记录调查进展或背景信息）

include 参数

大多数读取工具都接受可选的 include 参数，即要返回的字段名称列表。指定后，每个响应对象中只会包含这些字段，从而减少大模型上下文中的令牌用量。

# Return only id, title, and status for each incident
get_incidents(include=["id", "title", "status"])

# Return only id and name for each service
get_services(include=["id", "name"])

请参阅工具文档，了解每个工具可用字段的完整列表。

响应格式

所有 API 响应都遵循一致的格式：

{
  "metadata": {
    "count": "<int>",
    "description": "<str>"
  },
  "<resource_type>": [
    {
      "...": "..."
    }
  ],
  "error": {
    "message": "<str>",
    "code": "<str>"
  }
}

仅在发生错误时才会包含 error 字段。为保持一致，响应中的资源名称始终使用复数形式，即使只返回单个项目也是如此。

错误处理

发生错误时，响应会包含一个错误对象，其结构如下：

{
  "metadata": {
    "count": 0,
    "description": "Error occurred while processing request"
  },
  "error": {
    "message": "Invalid user ID provided",
    "code": "INVALID_USER_ID"
  }
}

常见错误情况包括：

• 无效的资源 ID（例如，user_id、team_id、service_id）
• 缺少必需参数
• 参数值无效
• API 请求失败
• 响应处理错误

参数验证

• 所有 ID 值（单 ID 参数和 team_ids 等列表筛选器）只能包含 ASCII 字母和数字；其他任何值都会返回错误
• 日期参数必须是有效的 ISO8601 时间戳
• 列表参数（例如，statuses、team_ids）必须包含有效值
• 在 ID 列表筛选器中，会移除首尾空白字符，并忽略空白 ID
• 必需参数不能为 None 或空字符串
• 对于 get_incidents 中的 statuses，仅 triggered、acknowledged 和 resolved 是有效值
• 对于事件中的 urgency，仅 high 和 low 是有效值
• 可使用 limit 参数限制列表操作返回的结果数量

速率限制和分页

• 服务会遵守 PagerDuty 的速率限制
• 服务会自动为你处理分页
• 可使用 limit 参数控制列表操作返回的结果数量
• 如果未指定 limit，服务默认最多返回 pagerduty_mcp_server.utils.RESPONSE_LIMIT 条结果

用户上下文

许多函数都接受 current_user_context 参数（默认为 True），该参数会根据此上下文自动筛选结果。当 current_user_context 为 True 时，不能使用某些筛选参数，因为它们会与自动筛选冲突：

• 对于事件：
  • team_ids 和 service_ids 不能与 current_user_context=True 一起使用
• 对于服务：
  • team_ids 不能与 current_user_context=True 一起使用
• 对于升级策略：
  • user_ids 和 team_ids 不能与 current_user_context=True 一起使用
• 对于用户：
  • team_ids 不能与 current_user_context=True 一起使用
• 对于值班安排：
  • user_ids 和 escalation_policy_ids 不能与 current_user_context=True 一起使用
  • 仍可使用 schedule_ids 按特定值班计划筛选
  • 查询将显示当前用户所属升级策略的值班安排
  • 如果当前用户不属于任何升级策略，且未提供 schedule_ids，该工具将返回错误；请改用 current_user_context=False 并指定筛选条件

开发

运行测试

测试套件包含单元测试和集成测试。集成测试需要连接真实的 PagerDuty API，而单元测试无需访问 API 即可运行。

pytest-cov 参数为可选参数，可用于在输出中包含测试覆盖率报告。

运行所有测试（如果未设置 PAGERDUTY_API_TOKEN，集成测试将自动跳过）：

uv run pytest [--cov=src --cov-report=term-missing]

仅运行单元测试（无需 API 令牌）：

uv run pytest -m unit [--cov=src --cov-report=term-missing]

仅运行集成测试（需要在环境中设置 PAGERDUTY_API_TOKEN）：

uv run pytest -m integration [--cov=src --cov-report=term-missing]

仅运行与特定子模块相关的测试：

uv run pytest -m <client|escalation_policies|...> [--cov=src --cov-report=term-missing]

使用 MCP Inspector 调试服务器

npx @modelcontextprotocol/inspector uv run pagerduty-mcp-server

文档

工具文档 - 关于可用工具的详细信息，包括参数、返回类型和示例查询

约定

• 所有 API 响应都遵循包含元数据、资源列表和可选错误的标准格式
• 为保持一致，响应中的资源名称始终使用复数形式
• 所有返回单个项目的函数仍会返回包含一个元素的列表
• 错误响应包含消息和代码
• 所有时间戳均采用 ISO8601 格式
• 测试使用 pytest 标记注明测试类型（单元测试/集成测试）和所测试的资源（事件、团队等）

示例查询

• 目前 PagerDuty 中有分配给我的事件吗？
• 接下来 2 周内我有即将开始的值班安排吗？
• 个性化团队还有哪些成员？