PagerDuty MCP Server

PagerDuty MCP Server

PagerDuty API の機能を LLM に提供するサーバーです。このサーバーは、構造化された入力と出力を使用して、プログラムから利用することを想定して設計されています。

概要

PagerDuty MCP Server は、PagerDuty API を操作するためのツール一式を提供します。これらのツールは、LLM がインシデント、サービス、チーム、ユーザーなどの 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 は、ローカルで単独利用する場合に使用できます。認証用のブラウザーが開き、トークンは OS のキーリングに安全に保存されます。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 を設定します（機密クライアント）。
• デフォルトのコールバックポート（5173）を変更するには、PAGERDUTY_OAUTH_CALLBACK_PORT を設定します。

使用方法

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 パラメーターを使用できます。指定すると、各レスポンスオブジェクトにはそれらのフィールドのみが含まれるため、LLM のコンテキストでのトークン使用量を削減できます。

# 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 の場合、自動フィルタリングと競合するため、次のフィルターパラメーターは使用できません。

• インシデントの場合：
  • 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 は使用できません
  • 特定のスケジュールで絞り込む場合は、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 レスポンスは、メタデータ、リソースのリスト、任意のエラーを含む標準形式に従います
• 一貫性を保つため、レスポンス内のリソース名は常に複数形にします
• 単一の項目を返す関数も、要素が 1 つのリストを返します
• エラーレスポンスには、メッセージとコードの両方が含まれます
• すべてのタイムスタンプは ISO8601 形式です
• テストには pytest マーカーを付け、テストの種類（ユニット／統合）と対象のリソース（インシデント、チームなど）を示します

クエリの例

• 現在、pagerduty で自分に割り当てられているインシデントはありますか？
• 今後 2 週間にオンコールの予定はありますか？
• personalization チームには、ほかに誰が所属していますか？