| Name | pagerduty-mcp-server JSON |
| Version |
1.0.0
JSON |
| download |
| home_page | None |
| Summary | MCP server for LLM agents to interact with PagerDuty SaaS |
| upload_time | 2025-03-21 20:47:36 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.13 |
| license | None |
| keywords |
pagerduty
mcp
llm
api
server
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# 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
```bash
pip install pagerduty-mcp-server
```
### From Source
```sh
# 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:
```bash
PAGERDUTY_API_KEY=your_api_key_here
```
## Usage
### As Goose Extension
```json
{
"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
```sh
uv run python -m pagerduty_mcp_server
```
## Response Format
All API responses follow a consistent format:
```json
{
"metadata": {
"count": <int>, // Number of results
"description": "<str>" // A short summary of the results
},
<resource_type>: [ // Always pluralized for consistency, even if one result is returned
{
...
},
...
],
"error": { // Only present if there's an error
"message": "<str>", // Human-readable error description
"code": "<str>" // Machine-readable error code
}
}
```
### Error Handling
When an error occurs, the response will include an error object with the following structure:
```json
{
"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
### Rate Limiting and Pagination
- The server respects PagerDuty's rate limits
- The server automatically handles pagination for you
### Example Usage
```python
from pagerduty_mcp_server import incidents
# 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'
)
```
## User Context
Many functions support automatic filtering based on the current user's context. When `current_user_context=True` (default), results are filtered to only show resources the current user has access to:
- Incidents for teams the user belongs to
- Services the user has access to
- Teams the user belongs to
- Escalation policies the user is part of
When using `current_user_context=True` (default), you cannot use `user_ids`, `team_ids`, or `service_ids` parameters as they would conflict with the automatic filtering.
## 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.
```bash
uv run pytest
```
To run only unit tests (i.e. tests that don't require `PAGERDUTY_API_KEY` set in the environment):
```sh
uv run pytest -m unit
```
To run only integration tests:
```bash
uv run python -m integration
```
To run only parser tests:
```bash
uv run python -m parsers
```
To run only tests related to a specific submodule:
```bash
uv run python -m <client|escalation_policies|...>
```
### Debug Server with MCP Inspector
```bash
npx @modelcontextprotocol/inspector uv run python -m pagerduty_mcp_server
```
## Reference
### Documentation
[Tool Documentation](./docs/tools.md) - 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)
Raw data
{
"_id": null,
"home_page": null,
"name": "pagerduty-mcp-server",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.13",
"maintainer_email": null,
"keywords": "pagerduty, mcp, llm, api, server",
"author": null,
"author_email": "Will Pfleger <wpfleger@block.xyz>",
"download_url": "https://files.pythonhosted.org/packages/cb/d9/eb9c044d2b5c46ae553f9aa6c936deaf03a042851b955f332bb5043fc711/pagerduty_mcp_server-1.0.0.tar.gz",
"platform": null,
"description": "# PagerDuty MCP Server\nA server that exposes PagerDuty API functionality to LLMs. This server is designed to be used programmatically, with structured inputs and outputs.\n\n## Overview\nThe 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.\n\n## Installation\n### From PyPI\n```bash\npip install pagerduty-mcp-server\n```\n\n### From Source\n```sh\n# Clone the repository\ngit clone https://github.com/wpfleger96/pagerduty-mcp-server.git\ncd pagerduty-mcp-server\n\n# Install dependencies\nbrew install uv\nuv sync\n```\n\n## Requirements\n- Python 3.13 or higher\n- PagerDuty API key\n\n## Configuration\nThe PagerDuty MCP Server requires a PagerDuty API key to be set in the environment:\n```bash\nPAGERDUTY_API_KEY=your_api_key_here\n```\n\n## Usage\n### As Goose Extension\n```json\n{\n \"type\": \"stdio\",\n \"enabled\": true,\n \"args\": [\n \"run\",\n \"python\",\n \"-m\",\n \"pagerduty_mcp_server\"\n ],\n \"commandInput\": \"uv run python -m pagerduty_mcp_server\",\n \"timeout\": 300,\n \"id\": \"pagerduty-mcp-server\",\n \"name\": \"pagerduty-mcp-server\",\n \"description\": \"pagerduty-mcp-server\",\n \"env_keys\": [\n \"PAGERDUTY_API_KEY\"\n ],\n \"cmd\": \"uv\"\n}\n```\n\n### As Standalone Server\n```sh\nuv run python -m pagerduty_mcp_server\n```\n\n## Response Format\nAll API responses follow a consistent format:\n```json\n{\n \"metadata\": {\n \"count\": <int>, // Number of results\n \"description\": \"<str>\" // A short summary of the results\n },\n <resource_type>: [ // Always pluralized for consistency, even if one result is returned\n {\n ...\n },\n ...\n ],\n \"error\": { // Only present if there's an error\n \"message\": \"<str>\", // Human-readable error description\n \"code\": \"<str>\" // Machine-readable error code\n }\n}\n```\n\n### Error Handling\nWhen an error occurs, the response will include an error object with the following structure:\n```json\n{\n \"metadata\": {\n \"count\": 0,\n \"description\": \"Error occurred while processing request\"\n },\n \"error\": {\n \"message\": \"Invalid user ID provided\",\n \"code\": \"INVALID_USER_ID\"\n }\n}\n```\n\nCommon error scenarios include:\n- Invalid resource IDs (e.g., user_id, team_id, service_id)\n- Missing required parameters\n- Invalid parameter values\n- API request failures\n- Response processing errors\n\n### Parameter Validation\n- All ID parameters must be valid PagerDuty resource IDs\n- Date parameters must be valid ISO8601 timestamps\n- List parameters (e.g., `statuses`, `team_ids`) must contain valid values\n- Invalid values in list parameters will be ignored\n- Required parameters cannot be `None` or empty strings\n- For `statuses` in `list_incidents`, only `triggered`, `acknowledged`, and `resolved` are valid values\n- For `urgency` in incidents, only `high` and `low` are valid values\n\n### Rate Limiting and Pagination\n- The server respects PagerDuty's rate limits\n- The server automatically handles pagination for you\n\n### Example Usage\n```python\nfrom pagerduty_mcp_server import incidents\n\n# List all incidents (including resolved) for the current user's teams\nincidents_list = incidents.list_incidents()\n\n# List only active incidents\nactive_incidents = incidents.list_incidents(statuses=['triggered', 'acknowledged'])\n\n# List incidents for specific services\nservice_incidents = incidents.list_incidents(service_ids=['SERVICE-1', 'SERVICE-2'])\n\n# List incidents for specific teams\nteam_incidents = incidents.list_incidents(team_ids=['TEAM-1', 'TEAM-2'])\n\n# List incidents within a date range\ndate_range_incidents = incidents.list_incidents(\n since='2024-03-01T00:00:00Z',\n until='2024-03-14T23:59:59Z'\n)\n```\n\n## User Context\nMany functions support automatic filtering based on the current user's context. When `current_user_context=True` (default), results are filtered to only show resources the current user has access to:\n- Incidents for teams the user belongs to\n- Services the user has access to\n- Teams the user belongs to\n- Escalation policies the user is part of\n\nWhen using `current_user_context=True` (default), you cannot use `user_ids`, `team_ids`, or `service_ids` parameters as they would conflict with the automatic filtering.\n\n## Development\n### Running Tests\nNote 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.\n\n```bash\nuv run pytest\n```\n\nTo run only unit tests (i.e. tests that don't require `PAGERDUTY_API_KEY` set in the environment):\n```sh\nuv run pytest -m unit\n```\n\nTo run only integration tests:\n```bash\nuv run python -m integration\n```\n\nTo run only parser tests:\n```bash\nuv run python -m parsers\n```\n\nTo run only tests related to a specific submodule:\n```bash\nuv run python -m <client|escalation_policies|...>\n```\n\n### Debug Server with MCP Inspector\n```bash\nnpx @modelcontextprotocol/inspector uv run python -m pagerduty_mcp_server\n```\n\n## Reference\n\n### Documentation\n[Tool Documentation](./docs/tools.md) - Detailed information about available tools including parameters, return types, and example queries\n\n### Conventions\n- All API responses follow the standard format with metadata, resource list, and optional error\n- Resource names in responses are always pluralized for consistency\n- All functions that return a single item still return a list with one element\n- Error responses include both a message and a code\n- All timestamps are in ISO8601 format\n- 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)\n",
"bugtrack_url": null,
"license": null,
"summary": "MCP server for LLM agents to interact with PagerDuty SaaS",
"version": "1.0.0",
"project_urls": {
"Bug Tracker": "https://github.com/wpfleger96/pagerduty-mcp-server/issues",
"Changelog": "https://github.com/wpfleger96/pagerduty-mcp-server/blob/main/CHANGELOG.md",
"Documentation": "https://github.com/wpfleger96/pagerduty-mcp-server#readme",
"Homepage": "https://github.com/wpfleger96/pagerduty-mcp-server",
"Repository": "https://github.com/wpfleger96/pagerduty-mcp-server.git"
},
"split_keywords": [
"pagerduty",
" mcp",
" llm",
" api",
" server"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "18c206e0116385730ba7d50096c30786b2d6e632eace765a5001fa9814dea2fe",
"md5": "d4c1fcaca1cbdec8aab42f78cde9f23a",
"sha256": "f16778f7b66be7a6493537dfc589f507c9976efe90c3d2f40824fee594629640"
},
"downloads": -1,
"filename": "pagerduty_mcp_server-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d4c1fcaca1cbdec8aab42f78cde9f23a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.13",
"size": 27686,
"upload_time": "2025-03-21T20:47:35",
"upload_time_iso_8601": "2025-03-21T20:47:35.252275Z",
"url": "https://files.pythonhosted.org/packages/18/c2/06e0116385730ba7d50096c30786b2d6e632eace765a5001fa9814dea2fe/pagerduty_mcp_server-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "cbd9eb9c044d2b5c46ae553f9aa6c936deaf03a042851b955f332bb5043fc711",
"md5": "b5b3afbbc158831734d8d500a5cc4235",
"sha256": "f80446f8c7d822e959bbcfb112b1c7827a4a0165a4168014d950deaa1ee7a63e"
},
"downloads": -1,
"filename": "pagerduty_mcp_server-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "b5b3afbbc158831734d8d500a5cc4235",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.13",
"size": 19079,
"upload_time": "2025-03-21T20:47:36",
"upload_time_iso_8601": "2025-03-21T20:47:36.251636Z",
"url": "https://files.pythonhosted.org/packages/cb/d9/eb9c044d2b5c46ae553f9aa6c936deaf03a042851b955f332bb5043fc711/pagerduty_mcp_server-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-03-21 20:47:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "wpfleger96",
"github_project": "pagerduty-mcp-server",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pagerduty-mcp-server"
}
