Configuration

Complete configuration guide for the Alertmanager MCP Server including environment variables, Docker setup, multi-backend configuration, and silence safety settings.

---

Prerequisites

Requirement	Description
Alertmanager	Access to an Alertmanager instance (v0.25+, standalone or clustered)
Docker	For containerized deployment (recommended)
Python 3.12+	For local development

---

Installation Options

Option 1: Docker (Recommended)

# Pull the latest image
docker pull talkopsai/alertmanager-mcp-server:latest

# Run with default configuration
docker run --rm -it \
  -p 8768:8768 \
  -e ALERTMANAGER_BASE_URL=http://host.docker.internal:9093 \
  -e MCP_TRANSPORT=http \
  talkopsai/alertmanager-mcp-server:latest

Option 2: From Source (Python)

# Install uv if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone the repository
git clone https://github.com/talkops-ai/talkops-mcp.git
cd talkops-mcp/src/alertmanager-mcp-server

# Create virtual environment and install
uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"

# Configure .env
cp .env.example .env
# Edit .env — at minimum set ALERTMANAGER_BASE_URL

# Run the server
uv run alertmanager-mcp-server

Run tests (with the venv activated):

pytest tests/

---

Environment Variables

Server Configuration

Variable	Default	Description
MCP_SERVER_NAME	alertmanager-mcp-server	Server name identifier
MCP_SERVER_VERSION	0.1.0	Server version string
MCP_TRANSPORT	stdio	Transport mode: http, sse, streamable-http, or stdio
MCP_HOST	0.0.0.0	Host address for HTTP server
MCP_PORT	8768	Port for HTTP server
MCP_PATH	/mcp	MCP endpoint path
MCP_LOG_LEVEL	INFO	Log level: DEBUG, INFO, WARNING, ERROR
MCP_LOG_FORMAT	json	Log format: json or text

Alertmanager Backend (Single)

Variable	Default	Description
ALERTMANAGER_BASE_URL	http://localhost:9093	Alertmanager HTTP API base URL
ALERTMANAGER_BACKEND_ID	default	Backend identifier used in all tool calls
ALERTMANAGER_DISPLAY_NAME	(empty)	Human-readable backend name
ALERTMANAGER_AUTH_HEADER	(empty)	Authorization header value (e.g. Bearer <token>)
ALERTMANAGER_VERIFY_SSL	true	Verify SSL certificates
ALERTMANAGER_TIMEOUT	30	HTTP timeout for Alertmanager API calls (seconds)

Alertmanager Backends (Multi)

For multiple backends, set ALERTMANAGER_BACKENDS as a JSON array:

ALERTMANAGER_BACKENDS='[
  {"id": "prod", "base_url": "https://alertmanager-prod.example.com", "labels": {"env": "prod"}},
  {"id": "staging", "base_url": "https://alertmanager-staging.example.com", "labels": {"env": "staging"}}
]'

When ALERTMANAGER_BACKENDS is set, the single-backend env vars are ignored.

Silence Safety

Variable	Default	Description
AM_MAX_SILENCE_MINUTES	1440	Maximum silence duration in minutes (24 hours)
AM_SILENCE_WARNING_THRESHOLD	50	Warn if a silence would affect ≥ N alerts

tip

These safety parameters exist to prevent overly broad or long-lived silences from masking real incidents. Adjust them based on your team's policies.

---

MCP Client Configuration

The server listens on http://localhost:8768/mcp by default:

{
  "mcpServers": {
    "alertmanager": {
      "url": "http://localhost:8768/mcp",
      "description": "MCP Server for Alertmanager alert triage, silence management, and routing"
    }
  }
}

For stdio transport:

{
  "mcpServers": {
    "alertmanager": {
      "command": "uv",
      "args": ["run", "alertmanager-mcp-server"],
      "env": {
        "ALERTMANAGER_BASE_URL": "http://localhost:9093",
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

---

Troubleshooting

Backend Connection Issues

1. Verify ALERTMANAGER_BASE_URL points to a reachable instance
2. Load the am://system/backends resource to check health status
3. If using auth, verify ALERTMANAGER_AUTH_HEADER is set correctly
4. For SSL issues, try ALERTMANAGER_VERIFY_SSL=false (development only)

Silence Creation Failures

1. Duration cap exceeded: Default cap is 24 hours. Increase AM_MAX_SILENCE_MINUTES or use shorter durations
2. Duplicate silence: An equivalent active silence already exists. Use am_list_silences to find it
3. Missing matchers: At least one matcher is required. Use am_preview_silence first

Routing Simulation Issues

1. Empty routing tree: Check am://system/config to verify configuration is loaded
2. No receivers found: Verify Alertmanager has receivers in its alertmanager.yml
3. Unexpected routing: Use am_explain_routing with specific labels to trace the routing path

---

Next Steps

• Tools — Full reference for all 14 MCP tools
• Resources — 11 MCP resources for discovery and monitoring
• Common Workflows — Step-by-step workflow guides
• Examples — Quick reference and natural language prompts