Opsgenie MCP Server
A Model Context Protocol (MCP) server that provides comprehensive Opsgenie alert management capabilities.
Features
- Complete Alert Management: List, create, acknowledge, and close alerts
- Alert Notes: Add and retrieve notes for alerts
- Alert Logs: View alert activity logs
- Custom Details: Add custom properties to alerts
- Multiple Transport Support: stdio, HTTP, and Server-Sent Events (SSE)
- Built with TypeScript and the official MCP SDK
Installation
Installing via Smithery
To install opsgenie-mcp-server for Claude Desktop automatically via Smithery:
npx -y @smithery/cli install @burakdirin/opsgenie-mcp-server --client claude
From npm (recommended)
npm install -g opsgenie-mcp-server
Or add to your project:
npm install opsgenie-mcp-server
From source
git clone https://github.com/burakdirin/opsgenie-mcp-server.git
cd opsgenie-mcp-server
npm install
npm run build
Usage
Transport Options
The server supports multiple transport protocols with flexible API key configuration:
1. Stdio Transport (Default) - For Desktop Integration
With Environment Variable:
export OPSGENIE_API_KEY="your-api-key-here"
npm run start:stdio
# or
node build/index.js --transport stdio
With CLI Argument:
node build/index.js --transport stdio --api-key "your-api-key-here"
2. HTTP Transport - For Web Applications and Hosted Deployment
Basic HTTP Server:
# Start HTTP server (API key provided per-request)
npm run start:http
# or
node build/index.js --transport http --port 3000
With Environment Variable:
export OPSGENIE_API_KEY="your-api-key-here"
node build/index.js --transport http --port 3000
HTTP API Key Configuration:
When using HTTP transport, clients can provide API keys through multiple methods:
- Environment Variable:
OPSGENIE_API_KEY=your-key - Custom Header:
X-Opsgenie-API-Key: your-key - Authorization Header:
Authorization: Bearer your-key - Query Parameter:
?apiKey=your-key
HTTP endpoints:
- Modern clients:
POST http://localhost:3000/mcp - Legacy clients:
GET http://localhost:3000/sse(Server-Sent Events)
3. Custom Port
node build/index.js --transport http --port 8080 --api-key "your-api-key-here"
Command Line Options
opsgenie-mcp-server [options]
Options:
-V, --version output the version number
-t, --transport <type> transport type (stdio|http) (default: "stdio")
-p, --port <number> port number for HTTP transport (default: "3000")
-a, --api-key <key> Opsgenie API key (can also use OPSGENIE_API_KEY env var)
-h, --help display help for command
Authentication
The Opsgenie MCP server supports multiple ways to provide your API key for authentication:
Option 1: Environment Variable (Recommended)
export OPSGENIE_API_KEY="your-api-key-here"
opsgenie-mcp-server --transport stdio
Option 2: CLI Argument
opsgenie-mcp-server --transport stdio --api-key "your-api-key-here"
Option 3: Per-tool Parameter (Backwards Compatible)
When using tools directly, you can still provide the API key as a parameter:
opsgenie_list_alerts: {"apiKey": "your-api-key-here"}
All Opsgenie API operations require an API key. You can obtain one from your Opsgenie account:
- Go to Opsgenie Settings → API Key Management
- Create a new API key with appropriate permissions
- Use this key in the
apiKeyparameter for all tool calls
Getting Your Opsgenie API Key
- Login to Opsgenie: Go to app.opsgenie.com
- Navigate to Settings: Click on your profile icon → Settings
- API Key Management: Go to "API Key Management" section
- Create New Key: Click "Create API Key"
- Set Permissions: Grant the following permissions:
- Configuration Access: Read, Create, Update, Delete
- Alert: Read, Create, Update, Delete
- Incident: Read, Create, Update, Delete
- Copy the Key: Save the generated API key securely
Using the API Key
With the improved API key handling, you now have several options:
Option 1: Set globally via environment variable (Recommended)
export OPSGENIE_API_KEY="genie-api-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
Then use tools without specifying the API key:
- "List my recent Opsgenie alerts"
- "Create a high priority alert for database connection failure"
- "Add a note to alert 12345 saying 'Investigating database connection issue'"
Option 2: Provide API key per tool (Backwards compatible)
- "List alerts using API key genie-api-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
- "Create alert with API key genie-api-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
Option 3: Using hosted server (Users provide their own keys) Users configure their client with their API key, and all tools work seamlessly:
- "List my recent Opsgenie alerts" (API key from client configuration)
- "Create a new high priority alert" (API key from client configuration)
Security Best Practices
- Never commit API keys to version control
- Store API keys securely (use environment variables or secure vaults)
- Rotate API keys periodically
- Use API keys with minimal required permissions
- Monitor API key usage in Opsgenie logs
Security
- All requests use HTTPS when connecting to Opsgenie API
- API keys should be stored securely and not exposed in logs
- Rate limiting is handled by the Opsgenie API
Available Tools
- opsgenie_list_alerts: List alerts from Opsgenie with filtering options
- opsgenie_create_alert: Create a new alert in Opsgenie
- opsgenie_acknowledge_alert: Acknowledge an existing alert
- opsgenie_close_alert: Close an alert
- opsgenie_list_alert_notes: List notes for a specific alert
- opsgenie_add_note: Add a note to an alert
- opsgenie_list_alert_logs: List activity logs for an alert
- opsgenie_add_details: Add custom details/properties to an alert
All tools require an Opsgenie API key for authentication.
Integration with Cursor IDE
To use this MCP server with Cursor IDE, you can configure it locally or connect to a hosted instance:
Local Installation Configuration
Method 1: Using Environment Variable (Recommended)
-
Set your API key as an environment variable:
export OPSGENIE_API_KEY="your-api-key-here" -
Configure in Cursor settings:
{ "mcpServers": { "opsgenie-mcp-server": { "command": "npx", "args": ["-y", "opsgenie-mcp-server", "--transport", "stdio"], "env": { "OPSGENIE_API_KEY": "your-api-key-here" } } } }
Method 2: Using CLI Argument
{
"mcpServers": {
"opsgenie-mcp-server": {
"command": "npx",
"args": [
"-y",
"opsgenie-mcp-server",
"--transport", "stdio",
"--api-key", "your-api-key-here"
]
}
}
}
Hosted Server Configuration
When connecting to a hosted MCP server (HTTP transport), you can provide your API key through various methods:
Option 1: Environment Variables
{
"mcpServers": {
"opsgenie-hosted": {
"url": "https://your-server.com/mcp",
"env": {
"OPSGENIE_API_KEY": "your-api-key-here"
}
}
}
}
Option 2: Custom Headers
{
"mcpServers": {
"opsgenie-hosted": {
"url": "https://your-server.com/mcp",
"headers": {
"X-Opsgenie-API-Key": "your-api-key-here"
}
}
}
}
Option 3: Authorization Header
{
"mcpServers": {
"opsgenie-hosted": {
"url": "https://your-server.com/mcp",
"headers": {
"Authorization": "Bearer your-api-key-here"
}
}
}
}
Option 4: Query Parameter
{
"mcpServers": {
"opsgenie-hosted": {
"url": "https://your-server.com/mcp?apiKey=your-api-key-here"
}
}
}
Configuration File Locations
macOS/Linux: ~/.cursor/mcp.json
Windows: %USERPROFILE%\.cursor\mcp.json
Verification
After configuration:
- Restart Cursor IDE
- The MCP server should appear in the MCP tab of Cursor Settings
- You can verify it's working by asking Cursor's AI assistant to list Opsgenie alerts
Example prompts to test:
- "List my recent Opsgenie alerts"
- "Create a new alert in Opsgenie for database connection failure"
- "Show me notes for alert ID 12345"
Deploying as a Hosted Service
You can deploy this MCP server as a hosted service to allow multiple users to connect with their own Opsgenie API keys:
Docker Deployment
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build
EXPOSE 3000
CMD ["node", "build/index.js", "--transport", "http", "--port", "3000"]
docker build -t opsgenie-mcp-server .
docker run -p 3000:3000 opsgenie-mcp-server
Vercel Deployment
Create a vercel.json file:
{
"functions": {
"api/mcp.js": {
"runtime": "nodejs18.x"
}
},
"routes": [
{
"src": "/mcp",
"dest": "/api/mcp.js"
}
]
}
Deploy:
vercel deploy
Railway Deployment
Create a railway.toml file:
[build]
builder = "NIXPACKS"
[deploy]
startCommand = "npm start"
healthcheckPath = "/health"
healthcheckTimeout = 300
restartPolicyType = "ON_FAILURE"
restartPolicyMaxRetries = 10
Client Configuration for Hosted Servers
Once deployed, users can connect to your hosted server by configuring their MCP client:
Claude Desktop Configuration:
{
"mcpServers": {
"opsgenie": {
"url": "https://your-domain.com/mcp",
"headers": {
"X-Opsgenie-API-Key": "user-specific-api-key"
}
}
}
}
Cursor IDE Configuration:
{
"mcpServers": {
"opsgenie": {
"url": "https://your-domain.com/mcp",
"env": {
"OPSGENIE_API_KEY": "user-specific-api-key"
}
}
}
}
This approach allows you to host a single instance that multiple users can connect to, each with their own Opsgenie credentials.
Development
- Built with TypeScript
- Uses the official MCP SDK
- Supports modern ES modules