MCP 服务器

PagerDuty MCP Server

一个服务器，它向大型语言模型（LLM）公开 PagerDuty API 的功能，并使用结构化的输入和输出，从而能够管理事件、服务、团队和用户。

Tools

list_escalation_policies

List existing escalation policies based on the given criteria. Args: current_user_context (bool): Whether to use the current user's ID/team IDs context (default: True, cannot be used with user_ids or team_ids) query (str): Filter escalation policies whose names contain the search query (optional) user_ids (List[str]): Filter results to only escalation policies that include the given user IDs (optional, cannot be used with current_user_context) team_ids (List[str]): Filter results to only escalation policies assigned to teams with the given IDs (optional, cannot be used with current_user_context) Returns: Dict[str, Any]: Dictionary containing metadata (count, description) and a list of escalation policies matching the specified criteria

show_escalation_policy

Show details about a given escalation policy. Args: policy_id (str): The ID of the escalation policy to show Returns: Dict[str, Any]: Escalation policy object with detailed information

show_team

Get detailed information about a given team. Args: team_id (str): The ID of the team to get Returns: Dict[str, Any]: Team object with detailed information

show_current_user

Get the current user's PagerDuty profile including their teams, contact methods, and notification rules. Returns: Dict[str, Any]: The user object containing profile information in the following format (note this is non-exhaustive): { "name": "John Doe", "email": "john.doe@example.com", "role": "user", "description": "John Doe is a user at Example Inc.", "job_title": "Software Engineer", "teams": [ { "id": "P123456", "summary": "Team Name 1" }, ... ], "contact_methods": [ { "id": "P123456", "summary": "Mobile" }, ... ], "notification_rules": [ { "id": "P123456", "summary": "0 minutes: channel XYZ" }, ... ], "id": "P123456" }

list_incidents

List PagerDuty incidents based on specified filters. Args: current_user_context (bool): Boolean, use the current user's team_ids and service_ids to filter (default: True, cannot be used with service_ids or team_ids) service_ids (List[str]): list of PagerDuty service IDs to filter by (optional, cannot be used with current_user_context) team_ids (List[str]): list of PagerDuty team IDs to filter by (optional, cannot be used with current_user_context) statuses (List[str]): list of status values to filter by (optional). Valid values are: - 'triggered' - The incident is currently active (included by default) - 'acknowledged' - The incident has been acknowledged by a user (included by default) - 'resolved' - The incident has been resolved (excluded by default) since (str): Start of date range in ISO8601 format (optional). Default is 1 month ago until (str): End of date range in ISO8601 format (optional). Default is now Returns: Dict[str, Any]: Dictionary containing metadata (count, description) and a list of incidents matching the specified criteria

show_incident

Get detailed information about a given incident. Args: incident_id (str): The ID or number of the incident to get Returns: Dict[str, Any]: Incident object with detailed information

list_oncalls

List the on-call entries during a given time range. Args: current_user_context (bool): Use the current user's ID to filter (default: True, cannot be used with user_ids or escalation_policy_ids) schedule_ids (List[str]): Return only on-calls for the specified schedule IDs (optional) user_ids (List[str]): Return only on-calls for the specified user IDs (optional, cannot be used with current_user_context) escalation_policy_ids (List[str]): Return only on-calls for the specified escalation policy IDs (optional, cannot be used with current_user_context) since (str): Start of date range in ISO8601 format (optional). Default is 1 month ago until (str): End of date range in ISO8601 format (optional). Default is now Returns: Dict[str, Any]: Dictionary containing metadata (count, description) and a list of on-call entries matching the specified criteria

list_schedules

List the on-call schedules. Args: query (str): Filter schedules whose names contain the search query (optional) Returns: Dict[str, Any]: Dictionary containing metadata (count, description) and a list of schedules matching the specified criteria

show_schedule

Show detailed information about a given schedule. Args: schedule_id (str): The ID of the schedule to get since (str): The start of the time range over which you want to search. Defaults to 2 weeks before until if an until is given. (optional) until (str): The end of the time range over which you want to search. Defaults to 2 weeks after since if a since is given. (optional) Returns: Dict[str, Any]: Schedule object with detailed information

list_services

List existing PagerDuty services. Args: current_user_context (bool): Use the current user's team IDs to filter (default: True, cannot be used with team_ids) team_ids (List[str]): Filter results to only services assigned to teams with the given IDs (optional, cannot be used with current_user_context) query (str): Filter services whose names contain the search query (optional) Returns: Dict[str, Any]: Dictionary containing metadata (count, description) and a list of services matching the specified criteria

show_service

Get details about a given service. Args: service_id (str): The ID of the service to get Returns: Dict[str, Any]: Service object with detailed information

list_teams

List teams in your PagerDuty account. Args: query (str): Filter teams whose names contain the search query (optional) Returns: Dict[str, Any]: Dictionary containing metadata (count, description) and a list of teams matching the specified criteria

list_users

List users in PagerDuty. Args: current_user_context (bool): Use the current user's team IDs to filter (default: True, cannot be used with team_ids) team_ids (List[str]): A list of team IDs to filter users (optional, cannot be used with current_user_context) query (str): A search query to filter users (optional) Returns: Dict[str, Any]: Dictionary containing metadata (count, description) and a list of users matching the specified criteria

show_user

Get detailed information about a given user. Args: user_id (str): The ID of the user to get Returns: Dict[str, Any]: User object with detailed information

README

PagerDuty MCP 服务器

一个向 LLM 公开 PagerDuty API 功能的服务器。此服务器旨在通过结构化的输入和输出来进行编程使用。

概述

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

安装

从 PyPI 安装

pip install pagerduty-mcp-server

从源代码安装

# 克隆仓库
git clone https://github.com/wpfleger96/pagerduty-mcp-server.git
cd pagerduty-mcp-server

# 安装依赖
brew install uv
uv sync

要求

Python 3.13 或更高版本
PagerDuty API 密钥

配置

PagerDuty MCP 服务器需要设置 PagerDuty API 密钥到环境变量中：

PAGERDUTY_API_KEY=your_api_key_here

用法

作为 Goose 扩展

{
  "type": "stdio",
  "enabled": true,
  "args": [
    "run",
    "python",
    "-m",
    "pagerduty_mcp_server"
  ],
  "commandInput": "uv run python -m pagerduty_mcp_server",
  "timeout": 300,
  "id": "pagerduty-mcp-server",
  "name": "pagerduty-mcp-server",
  "description": "pagerduty-mcp-server",
  "env_keys": [
    "PAGERDUTY_API_KEY"
  ],
  "cmd": "uv"
}

作为独立服务器

uv run python -m pagerduty_mcp_server

响应格式

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

{
  "metadata": {
    "count": <int>,  // 结果数量
    "description": "<str>"  // 结果的简短摘要
  },
  <resource_type>: [ // 为了保持一致性，始终使用复数形式，即使只返回一个结果
    {
      ...
    },
    ...
  ],
  "error": {  // 仅在发生错误时出现
    "message": "<str>",  // 人类可读的错误描述
    "code": "<str>"  // 机器可读的错误代码
  }
}

错误处理

发生错误时，响应将包含一个具有以下结构的错误对象：

{
  "metadata": {
    "count": 0,
    "description": "处理请求时发生错误"
  },
  "error": {
    "message": "提供的用户 ID 无效",
    "code": "INVALID_USER_ID"
  }
}

常见的错误场景包括：

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

参数验证

所有 ID 参数必须是有效的 PagerDuty 资源 ID
日期参数必须是有效的 ISO8601 时间戳
列表参数（例如，statuses、team_ids）必须包含有效值
列表参数中的无效值将被忽略
必需的参数不能为 None 或空字符串
对于 list_incidents 中的 statuses，只有 triggered、acknowledged 和 resolved 是有效值
对于事件中的 urgency，只有 high 和 low 是有效值
limit 参数可用于限制列表操作返回的结果数量

速率限制和分页

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

使用示例

from pagerduty_mcp_server import incidents
from pagerduty_mcp_server.utils import RESPONSE_LIMIT

# 列出当前用户团队的所有事件（包括已解决的事件）
incidents_list = incidents.list_incidents()

# 仅列出活动事件
active_incidents = incidents.list_incidents(statuses=['triggered', 'acknowledged'])

# 列出特定服务的事件
service_incidents = incidents.list_incidents(service_ids=['SERVICE-1', 'SERVICE-2'])

# 列出特定团队的事件
team_incidents = incidents.list_incidents(team_ids=['TEAM-1', 'TEAM-2'])

# 列出某个日期范围内的事件
date_range_incidents = incidents.list_incidents(
    since='2024-03-01T00:00:00Z',
    until='2024-03-14T23:59:59Z'
)

# 列出限制结果数量的事件
limited_incidents = incidents.list_incidents(limit=10)

# 列出具有默认限制的事件
default_limit_incidents = incidents.list_incidents(limit=RESPONSE_LIMIT)

用户上下文

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

对于所有资源类型：
- user_ids 不能与 current_user_context=True 一起使用
对于事件：
- team_ids 和 service_ids 不能与 current_user_context=True 一起使用
对于服务：
- team_ids 不能与 current_user_context=True 一起使用
对于升级策略：
- team_ids 不能与 current_user_context=True 一起使用
对于值班人员：
- user_ids 不能与 current_user_context=True 一起使用
- schedule_ids 仍然可以用来按特定时间表进行过滤
- 该查询将显示与当前用户团队关联的所有升级策略的值班人员
- 这对于回答诸如“谁目前在我的团队值班？”之类的问题很有用
- 当前用户的 ID 不用作过滤器，因此您将看到所有在值班的团队成员

开发

运行测试

请注意，大多数测试都需要与 PagerDuty API 的真实连接，因此您需要在运行完整的测试套件之前在环境中设置 PAGERDUTY_API_KEY。

uv run pytest

要仅运行单元测试（即不需要在环境中设置 PAGERDUTY_API_KEY 的测试）：

uv run pytest -m unit

要仅运行集成测试：

uv run pytest -m integration

要仅运行解析器测试：

uv run pytest -m parsers

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

uv run pytest -m <client|escalation_policies|...>

使用 MCP Inspector 调试服务器

npx @modelcontextprotocol/inspector uv run python -m pagerduty_mcp_server

贡献

发布

此项目使用 Conventional Commits 进行自动发布。提交消息决定了版本升级：

feat: → 次版本 (1.0.0 → 1.1.0)
fix: → 补丁版本 (1.0.0 → 1.0.1)
BREAKING CHANGE: → 主版本 (1.0.0 → 2.0.0)

CHANGELOG.md、GitHub 版本和 PyPI 包会自动更新。

文档

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

约定

所有 API 响应都遵循标准格式，包括元数据、资源列表和可选错误
响应中的资源名称始终使用复数形式，以保持一致性
所有返回单个项目的函数仍然返回一个包含一个元素的列表
错误响应包括消息和代码
所有时间戳均为 ISO8601 格式
测试使用 pytest 标记来指示其类型（单元/集成）、它们测试的资源（事件、团队等）以及它们是否测试解析功能（“parsers”标记）