Skip to main content
This guide covers all methods for installing the PagerDuty MCP Server, from the simplest one-command installation to running from source.

​
System Requirements

Before installing, ensure your system meets these requirements:
  • Python: Version 3.12.x (Python 3.12.0 is recommended)
  • Operating System: Linux, macOS, or Windows
  • MCP Client: VS Code, Cursor, Claude Desktop, or any MCP-compatible client
The PagerDuty MCP Server specifically requires Python 3.12. Other versions may not work correctly.

​
Installation Methods

The easiest way to use the PagerDuty MCP Server is via uvx, which automatically manages dependencies and the Python environment.
1

Install uv

First, install uv if you don’t have it already:macOS/Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh
Windows:
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
For more installation options, see the official uv documentation.
2

Run the server

No additional installation needed! Just run:
uvx pagerduty-mcp
The uvx command automatically downloads and runs the latest version of the PagerDuty MCP Server.
This is the recommended method for most users. The uvx approach is used in all MCP client configurations throughout this documentation.

​
Method 2: Using pip

If you prefer traditional Python package installation, you can install via pip.
1

Ensure Python 3.12 is active

Verify you’re using Python 3.12:
python --version
Should output: Python 3.12.x
2

Install the package

Install the PagerDuty MCP Server:
pip install pagerduty-mcp
3

Run the server

After installation, you can run the server:
pagerduty-mcp
When using pip installation, you’ll need to ensure the package is installed in an environment accessible to your MCP client. Virtual environments may require additional configuration.

​
Method 3: From Source

For development or if you want to run the latest code, you can install from source.
1

Install prerequisites

Install asdf-vm and uv if not already installed.
2

Clone the repository

git clone https://github.com/pagerduty/pagerduty-mcp-server.git
cd pagerduty-mcp-server
3

Install asdf plugins

asdf plugin add python
asdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejs.git
asdf plugin add uv
4

Install tool versions

Install the correct versions of Python and other tools:
asdf install
5

Create virtual environment and install dependencies

uv sync
6

Ensure uv is available globally

Make sure uv is available globally so it can be invoked from your MCP client:Follow the official uv installation guide to install it globally.
You may need to restart your terminal and/or your MCP client for the changes to take effect.

​
Running from Source

When running from source, your MCP client configuration needs to be updated to use uv run instead of uvx:
settings.json
{
    "mcp": {
        "servers": {
            "pagerduty-mcp": { 
                "type": "stdio",
                "command": "uv",
                "args": [
                    "run",
                    "--directory",
                    "/path/to/pagerduty-mcp-server",
                    "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/pagerduty-mcp-server with the full path to your cloned repository (e.g., /Users/yourname/code/pagerduty-mcp-server).

​
Method 4: Using Docker

You can also run the PagerDuty MCP Server in a Docker container for an isolated and portable deployment.
1

Ensure Docker is installed

Make sure you have Docker installed on your system.
2

Build the Docker image

git clone https://github.com/pagerduty/pagerduty-mcp-server.git
cd pagerduty-mcp-server
docker build -t pagerduty-mcp:latest .
3

Run the container

Read-only mode (default):
docker run -i --rm \
  -e PAGERDUTY_USER_API_KEY="your-api-key-here" \
  pagerduty-mcp:latest
With write tools enabled:
docker run -i --rm \
  -e PAGERDUTY_USER_API_KEY="your-api-key-here" \
  pagerduty-mcp:latest --enable-write-tools
For EU region:
docker run -i --rm \
  -e PAGERDUTY_USER_API_KEY="your-api-key-here" \
  -e PAGERDUTY_API_HOST="https://api.eu.pagerduty.com" \
  pagerduty-mcp:latest

​
Using Docker with MCP Clients

To configure an MCP client to use the Docker container: 
{
  "mcpServers": {
    "pagerduty-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "PAGERDUTY_USER_API_KEY=your-api-key-here",
        "pagerduty-mcp:latest"
      ]
    }
  }
}
The Docker container uses stdio transport, making it compatible with MCP clients that expect standard input/output communication.

​
Verifying Installation

To verify that the PagerDuty MCP Server is installed correctly:

​
Check the Version

Run the server with the --help flag to see available options: 
uvx pagerduty-mcp --help
You should see output showing the available commands and options.

​
Test Server Startup

Set your API key as an environment variable and test the server: 
export PAGERDUTY_USER_API_KEY="your-api-key-here"
uvx pagerduty-mcp
You should see a message indicating the server has started: 
Starting PagerDuty MCP Server. Use the --enable-write-tools flag to enable write tools.
Press Ctrl+C to stop the test server.

​
Test with an MCP Client

The best way to verify everything is working is to configure an MCP client (like VS Code) and try a simple query. See the Quickstart Guide for step-by-step instructions.

​
Troubleshooting

​
Python Version Issues

Problem: Error message about Python version mismatch. Solution: Ensure you’re using Python 3.12.x: 
python --version
If you’re using the wrong version, install Python 3.12 using your system’s package manager or pyenv.

​
uv Not Found

Problem: uvx: command not found or uv: command not found Solution: Install uv globally following the official installation guide. After installation, restart your terminal and MCP client.

​
API Key Issues

Problem: Authentication errors or “API key not found” messages. Solution:
  • Verify your API key is correctly set in the MCP client configuration
  • Ensure there are no extra spaces or quotes around the key
  • Generate a new API key from your PagerDuty user settings if needed
  • Check that the key has not expired

​
EU Region Users

Problem: API calls failing with EU region accounts. Solution: Update the PAGERDUTY_API_HOST environment variable to https://api.eu.pagerduty.com in your MCP client configuration.

​
Server Not Starting in MCP Client

Problem: The server doesn’t appear in the MCP client or won’t start. Solution:
  1. Check that MCP is enabled in your client settings
  2. Verify the configuration syntax in your settings.json
  3. Restart the MCP client completely
  4. Check the MCP client logs for error messages
  5. Try restarting the server from the command palette (MCP: List Servers)

​
Permission Errors

Problem: Permission denied errors when running the server. Solution:
  • Ensure you have write permissions in your Python environment
  • If using a virtual environment, activate it before installing
  • On Unix systems, avoid using sudo with pip - use virtual environments instead

​
Import Errors

Problem: ModuleNotFoundError or import errors when running the server. Solution:
  • Reinstall the package: pip install --force-reinstall pagerduty-mcp
  • If using uvx, clear the cache: rm -rf ~/.local/share/uv
  • Ensure you’re using Python 3.12 and not another version

​
Configuration Options

The PagerDuty MCP Server accepts the following configuration options:

​
Command-Line Flags

  • --enable-write-tools: Enable write operations (create, update, delete). Default: disabled

​
Environment Variables

  • PAGERDUTY_USER_API_KEY (required): Your PagerDuty User API Token
  • PAGERDUTY_API_HOST (optional): PagerDuty API endpoint. Default: https://api.pagerduty.com
    • For EU accounts, use: https://api.eu.pagerduty.com

​
Upgrading

​
Upgrading uvx Installation

The uvx command automatically uses the latest version. To force an upgrade: 
uvx --refresh pagerduty-mcp

​
Upgrading pip Installation

Upgrade to the latest version: 
pip install --upgrade pagerduty-mcp

​
Upgrading Source Installation

Pull the latest changes and reinstall: 
cd pagerduty-mcp-server
git pull
uv sync

​
Upgrading Docker Installation

Rebuild the Docker image: 
cd pagerduty-mcp-server
git pull
docker build -t pagerduty-mcp:latest .

​
Next Steps

Now that you have the PagerDuty MCP Server installed:

Quickstart

Follow the quickstart guide to configure your first client

Configure Clients

Learn how to configure different MCP clients

Available Tools

Explore all available tools and capabilities

Usage Guides

Learn common workflows and best practices

Build docs developers (and LLMs) love

Get started for freeTalk to us