# PagerDuty MCP Server

A Model Context Protocol (MCP) server for PagerDuty integration that allows AI agents to interact with PagerDuty services, incidents, schedules, and on-call management.

## Features

- **List Services**: Browse and filter PagerDuty services
- **Incident Management**:
  - List incidents with advanced filtering (status, assignee, priority, service, date range)
  - Create new incidents
  - Update incidents (acknowledge, resolve, change priority, escalate)
  - Add responders to incidents
- **On-Call Management**: View current on-call schedules and users
- **Schedule Management**: List and browse schedules

## Prerequisites

- Node.js v18.0.0 or higher
- A PagerDuty account with API access
- PagerDuty API token

## Installation

1. Clone the repository:
```bash
git clone <repository-url>
cd pagerduty-mcp
```

2. Install dependencies:
```bash
npm install
```

3. Build the server:
```bash
npm run build
```

## Configuration

### Environment Variables

Create a `.env` file in the root directory (use `.env.example` as a template):

```bash
# Required: Your PagerDuty API token
PAGERDUTY_API_TOKEN=your_api_token_here

# Optional: PagerDuty API URL (defaults to https://api.pagerduty.com)
PAGERDUTY_API_URL=https://api.pagerduty.com
```

### Getting Your PagerDuty API Token

1. Log in to your PagerDuty account
2. Go to **Configuration** → **API Access**
3. Click **Create New API Key**
4. Provide a description and select appropriate permissions
5. Copy the generated token

## Usage

### Running the Server

```bash
npm start
```

### Using with Claude Desktop

Add the following configuration to your Claude Desktop config file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "pagerduty": {
      "command": "node",
      "args": ["/path/to/pagerduty-mcp/build/index.js"],
      "env": {
        "PAGERDUTY_API_TOKEN": "your_api_token_here",
        "PAGERDUTY_API_URL": "https://api.pagerduty.com"
      }
    }
  }
}
```

## Available Tools

### 1. list_services
List PagerDuty services with optional filtering.

**Parameters:**
- `limit` (number, optional): Maximum number of services to return (1-100, default: 25)
- `offset` (number, optional): Number of services to skip (default: 0)
- `query` (string, optional): Filter services by name or description

### 2. list_incidents
List incidents with comprehensive filtering options.

**Parameters:**
- `limit` (number, optional): Maximum number of incidents (1-100, default: 25)
- `offset` (number, optional): Number of incidents to skip (default: 0)
- `statuses` (array, optional): Filter by status (`triggered`, `acknowledged`, `resolved`)
- `service_ids` (array, optional): Filter by service IDs
- `user_ids` (array, optional): Filter by assigned user IDs
- `priority_ids` (array, optional): Filter by priority IDs
- `urgencies` (array, optional): Filter by urgency (`high`, `low`)
- `sort_by` (string, optional): Sort by field (`incident_number`, `created_at`, `updated_at`)
- `since` (string, optional): Show incidents created after this ISO 8601 date
- `until` (string, optional): Show incidents created before this ISO 8601 date

### 3. create_incident
Create a new PagerDuty incident.

**Parameters:**
- `title` (string, required): Incident title
- `service_id` (string, required): ID of the service
- `from` (string, required): Email of the user creating the incident
- `priority_id` (string, optional): Priority ID
- `urgency` (string, optional): Incident urgency (`high`, `low`)
- `incident_key` (string, optional): Unique key for deduplication
- `details` (string, optional): Incident body/details

### 4. update_incident
Update an existing incident (acknowledge, resolve, change priority, etc.).

**Parameters:**
- `incident_id` (string, required): ID of the incident to update
- `from` (string, required): Email of the user making the update
- `status` (string, optional): New status (`acknowledged`, `resolved`)
- `priority_id` (string, optional): New priority ID
- `assignee_ids` (array, optional): User IDs to assign
- `escalation_policy_id` (string, optional): New escalation policy ID

### 5. list_oncalls
List current on-call schedules and users.

**Parameters:**
- `schedule_ids` (array, optional): Filter by schedule IDs
- `user_ids` (array, optional): Filter by user IDs
- `escalation_policy_ids` (array, optional): Filter by escalation policy IDs
- `since` (string, optional): Show on-calls since this ISO 8601 date
- `until` (string, optional): Show on-calls until this ISO 8601 date

### 6. list_schedules
List PagerDuty schedules.

**Parameters:**
- `limit` (number, optional): Maximum number of schedules (1-100, default: 25)
- `offset` (number, optional): Number of schedules to skip (default: 0)
- `query` (string, optional): Filter schedules by name

### 7. add_responders
Add responders to an existing incident.

**Parameters:**
- `incident_id` (string, required): ID of the incident
- `message` (string, required): Message to send to responders
- `from` (string, required): Email of the user adding responders
- `requester_id` (string, required): ID of the user requesting responders
- `responder_ids` (array, optional): User IDs to add as responders
- `escalation_policy_ids` (array, optional): Escalation policy IDs to add

## Example Usage with Claude

Once configured, you can use natural language with Claude to interact with PagerDuty:

- "Show me all triggered incidents from the last 24 hours"
- "List all services that contain 'web' in their name"
- "Create a high priority incident for the API service with title 'Database Connection Issue'"
- "Who is currently on-call for the infrastructure team?"
- "Acknowledge incident #12345 and assign it to user ABC123"
- "Add responders to incident #67890 with message 'Need immediate assistance with database issue'"

## Development

### Build
```bash
npm run build
```

### Development Mode (with watch)
```bash
npm run dev
```

### Clean Build Directory
```bash
npm run clean
```

## Error Handling

The server includes comprehensive error handling for:
- Invalid PagerDuty API tokens
- Network connectivity issues
- Invalid parameters
- PagerDuty API rate limits
- Missing required fields

All errors are properly formatted and returned as MCP-compliant error responses.

## Security

- API tokens are loaded from environment variables only
- All API requests include proper authentication headers
- Input validation is performed on all parameters
- Sensitive information is never logged

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## License

MIT License - see LICENSE file for details.

## Support

For issues and questions:
1. Check the PagerDuty API documentation
2. Review the error messages in the console
3. Ensure your API token has the necessary permissions
4. Verify your environment configuration

## Changelog

### v1.0.0
- Initial release
- Full PagerDuty API integration
- MCP compliance
- Comprehensive incident management
- Service and schedule browsing
- On-call management
- Advanced filtering and search capabilities