What is Pagerduty Mcp Server

The PagerDuty MCP Server is a programmatic interface that provides functionalities for interacting with the PagerDuty API. It allows various operations on PagerDuty resources, such as incidents, services, teams, and users specifically designed for language models to access and manipulate PagerDuty data efficiently.

Use cases

Use cases include retrieving incident reports, managing on-call schedules, listing services or teams, and querying user information. Developers can automate the monitoring and management of incidents within their PagerDuty account or create integrations with other systems to enhance operational workflows.

How to use

To use the PagerDuty MCP Server, install it via PyPI or by cloning the repository. Set the environment variable for your PagerDuty API key, then run the server as a Goose extension or standalone server. Function calls are made to perform actions like listing incidents or services, with optional parameters for filtering and limitations on results.

Key features

Key features include a consistent response format for API operations, automatic handling of pagination, rate limiting compliance, and built-in error handling. The server supports user context filtering, enabling tailored queries based on the current user’s permissions and roles within PagerDuty.

Where to use

The PagerDuty MCP Server can be implemented in environments where automated incident response and management are necessary, such as DevOps teams, IT support workflows, and incident management systems. It is suitable for integration with chatbots, monitoring tools, and other applications requiring dynamic interaction with PagerDuty data.

PagerDuty MCP Server

A server that exposes PagerDuty API functionality to LLMs. This server is designed to be used programmatically, with structured inputs and outputs.

Overview

The PagerDuty MCP Server provides a set of tools for interacting with the PagerDuty API. These tools are designed to be used by LLMs to perform various operations on PagerDuty resources such as incidents, services, teams, and users.

Installation

From PyPI

pip install pagerduty-mcp-server

From Source

# Clone the repository
git clone https://github.com/wpfleger96/pagerduty-mcp-server.git
cd pagerduty-mcp-server

# Install dependencies
brew install uv
uv sync

Requirements

• Python 3.13 or higher
• PagerDuty API key

Configuration

The PagerDuty MCP Server requires a PagerDuty API key to be set in the environment:

PAGERDUTY_API_KEY=your_api_key_here

Usage

As Goose Extension

{
  "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"
}

As Standalone Server

uv run python -m pagerduty_mcp_server

Response Format

All API responses follow a consistent format:

Error Handling

When an error occurs, the response will include an error object with the following structure:

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

Common error scenarios include:

• Invalid resource IDs (e.g., user_id, team_id, service_id)
• Missing required parameters
• Invalid parameter values
• API request failures
• Response processing errors

Parameter Validation

• All ID parameters must be valid PagerDuty resource IDs
• Date parameters must be valid ISO8601 timestamps
• List parameters (e.g., statuses, team_ids) must contain valid values
• Invalid values in list parameters will be ignored
• Required parameters cannot be None or empty strings
• For statuses in list_incidents, only triggered, acknowledged, and resolved are valid values
• For urgency in incidents, only high and low are valid values
• The limit parameter can be used to restrict the number of results returned by list operations

Rate Limiting and Pagination

• The server respects PagerDuty’s rate limits
• The server automatically handles pagination for you
• The limit parameter can be used to control the number of results returned by list operations
• If no limit is specified, the server will return up to {pagerduty_mcp_server.utils.RESPONSE_LIMIT} results by default

Example Usage

from pagerduty_mcp_server import incidents
from pagerduty_mcp_server.utils import RESPONSE_LIMIT

# List all incidents (including resolved) for the current user's teams
incidents_list = incidents.list_incidents()

# List only active incidents
active_incidents = incidents.list_incidents(statuses=['triggered', 'acknowledged'])

# List incidents for specific services
service_incidents = incidents.list_incidents(service_ids=['SERVICE-1', 'SERVICE-2'])

# List incidents for specific teams
team_incidents = incidents.list_incidents(team_ids=['TEAM-1', 'TEAM-2'])

# List incidents within a date range
date_range_incidents = incidents.list_incidents(
    since='2024-03-01T00:00:00Z',
    until='2024-03-14T23:59:59Z'
)

# List incidents with a limit on the number of results
limited_incidents = incidents.list_incidents(limit=10)

# List incidents with the default limit
default_limit_incidents = incidents.list_incidents(limit=RESPONSE_LIMIT)

User Context

Many functions accept a current_user_context parameter (defaults to True) which automatically filters results based on this context. When current_user_context is True, you cannot use certain filter parameters as they would conflict with the automatic filtering:

• For all resource types:
  • user_ids cannot be used with current_user_context=True
• For incidents:
  • team_ids and service_ids cannot be used with current_user_context=True
• For services:
  • team_ids cannot be used with current_user_context=True
• For escalation policies:
  • team_ids cannot be used with current_user_context=True
• For on-calls:
  • user_ids cannot be used with current_user_context=True
  • schedule_ids can still be used to filter by specific schedules
  • The query will show on-calls for all escalation policies associated with the current user’s teams
  • This is useful for answering questions like “who is currently on-call for my team?”
  • The current user’s ID is not used as a filter, so you’ll see all team members who are on-call

Development

Running Tests

Note that most tests require a real connection to PagerDuty API, so you’ll need to set PAGERDUTY_API_KEY in the environment before running the full test suite.

uv run pytest

To run only unit tests (i.e. tests that don’t require PAGERDUTY_API_KEY set in the environment):

uv run pytest -m unit

To run only integration tests:

uv run pytest -m integration

To run only parser tests:

uv run pytest -m parsers

To run only tests related to a specific submodule:

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

Debug Server with MCP Inspector

npx @modelcontextprotocol/inspector uv run python -m pagerduty_mcp_server

Contributions

Releases

This project uses Conventional Commits for automated releases. Commit messages determine version bumps:

• feat: → minor version (1.0.0 → 1.1.0)
• fix: → patch version (1.0.0 → 1.0.1)
• BREAKING CHANGE: → major version (1.0.0 → 2.0.0)

The CHANGELOG.md, GitHub releases, and PyPI packages are updated automatically.

Documentation

Tool Documentation - Detailed information about available tools including parameters, return types, and example queries

Conventions

• All API responses follow the standard format with metadata, resource list, and optional error
• Resource names in responses are always pluralized for consistency
• All functions that return a single item still return a list with one element
• Error responses include both a message and a code
• All timestamps are in ISO8601 format
• Tests are marked with pytest markers to indicate their type (unit/integration), the resource they test (incidents, teams, etc.), and whether they test parsing functionality (“parsers” marker)