Skip to main content
This guide walks you through setting up the PagerDuty MCP Server for local development, allowing you to modify and test the server code.

​
Prerequisites

  • asdf: Version manager for managing Python, Node.js, and uv versions
  • uv: Fast Python package installer and resolver
  • Git (for cloning the repository)
  • A PagerDuty User API Token (see Prerequisites)

​
Installation Steps

​
1. Clone the Repository

Clone the PagerDuty MCP Server repository to your local machine: 
git clone <repository-url>
cd mcp-server

​
2. Install asdf Plugins

Install the required asdf plugins for Python, Node.js, and uv: 
asdf plugin add python
asdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejs.git
asdf plugin add uv

​
3. Install Tool Versions

Install the tool versions specified in the .tool-versions file: 
asdf install
This command reads the .tool-versions file and installs the correct versions of Python, Node.js, and uv.

​
4. Create Virtual Environment and Install Dependencies

Use uv to create a virtual environment and install dependencies: 
uv sync
This command:
  • Creates a virtual environment in .venv/
  • Installs all project dependencies
  • Installs the pagerduty_mcp package in editable mode

​
5. Ensure uv is Available Globally

The MCP server can be run from different places, so uv needs to be available globally. Follow the official uv installation documentation.
You may need to restart your terminal and/or VS Code for the changes to take effect.

​
Running Locally with uv

To run your cloned PagerDuty MCP Server, update your MCP client configuration to use uv instead of uvx.

​
Claude Desktop Configuration Example

{
  "pagerduty-mcp": { 
    "type": "stdio",
    "command": "uv",
    "args": [
      "run",
      "--directory",
      "/path/to/your/mcp-server-directory",
      "python",
      "-m",
      "pagerduty_mcp",
      "--enable-write-tools"
    ],
    "env": {
      "PAGERDUTY_USER_API_KEY": "${input:pagerduty-api-key}",
      "PAGERDUTY_API_HOST": "https://api.pagerduty.com"
    }
  }
}
Replace /path/to/your/mcp-server-directory with the full path to the directory where you cloned the MCP server, e.g., /Users/yourname/code/mcp-server

​
Configuration Details

  • —directory: Specifies the directory containing your local clone
  • —enable-write-tools: Enables write operations, allowing you to create incidents, schedule overrides, and more
  • PAGERDUTY_API_HOST: Use https://api.eu.pagerduty.com if your PagerDuty account is in the EU region

​
Development Workflow

The project includes a Makefile with useful development commands:

​
Running Tests

Run all unit tests: 
make test
Or use the direct command: 
uv run python -m pytest tests/ -v

​
Running Tests with Coverage

Generate a coverage report: 
make test-coverage
This runs tests and displays coverage for all tool modules.

​
HTML Coverage Report

Generate an HTML coverage report: 
make test-html-coverage
View the report by opening htmlcov/index.html in your browser.

​
Linting

Run linting checks: 
make lint
Or directly: 
uv run python -m ruff check .

​
Code Formatting

Format code automatically: 
make format
Or directly: 
uv run python -m ruff format .

​
Run All Checks

Run linting and tests with coverage: 
make check

​
Clean Generated Files

Remove generated files and caches: 
make clean

​
Install Development Dependencies

Install additional development dependencies: 
make dev-install
Or directly: 
uv sync --group dev

​
Debugging the MCP Server

You can debug the MCP server using the MCP Inspector: 
make debug
Or directly: 
npx @modelcontextprotocol/inspector uv run --directory ./ python -m pagerduty_mcp --enable-write-tools
This starts an interactive debugging session where you can test tools and inspect server behavior.

​
Available Make Commands

Here’s a quick reference of all available Make commands:
CommandDescription
make testRun all unit tests
make test-coverageRun tests with coverage report
make test-html-coverageRun tests with HTML coverage report
make cleanClean up generated files
make installInstall dependencies
make dev-installInstall development dependencies
make lintRun linting checks
make formatFormat code
make checkRun all checks (lint, format, test)
make debugStart MCP server debugging session

​
Troubleshooting

​
asdf Command Not Found

If asdf is not found, install it following the official asdf installation guide.

​
Python Version Mismatch

Ensure asdf install completed successfully and that the correct Python version is active: 
asdf current python

​
uv sync Fails

If uv sync fails:
  • Ensure asdf has installed the correct tool versions
  • Check that you’re in the project directory
  • Try running uv sync with verbose output: uv sync -v

​
Tests Failing

If tests fail:
  • Ensure all dependencies are installed: uv sync
  • Check that your API key is valid (if required for tests)
  • Run tests with verbose output: uv run python -m pytest tests/ -vv

​
Import Errors

If you encounter import errors when running the server:
  • Ensure the virtual environment is activated
  • Verify the package is installed in editable mode: uv sync
  • Check that you’re using the correct Python version

Build docs developers (and LLMs) love

Get started for freeTalk to us