devops-mcp

Unified MCP server for DevOps engineers — query and manage Kubernetes, ArgoCD, Prometheus, and PagerDuty from any MCP-compatible AI agent.

What is this?

devops-mcp is an open source Model Context Protocol server that gives AI agents (Claude, etc.) real-time read and write access to your infrastructure stack — all from a single install.

Instead of copy-pasting kubectl output into a chat window, you can ask:

"Why is the payments deployment in CrashLoopBackOff?" "What changed in the last ArgoCD sync for the auth app?" "Show me the p99 latency for the API gateway over the last hour." "Who's on call right now and what incidents are open?" "Debug the payments service - what's wrong with it?"

...and get live answers, sourced directly from your cluster and tooling.

Providers included:

Quick start

Claude Desktop (stdio — recommended)

Add this to ~/.config/claude/claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "devops": {
      "command": "npx",
      "args": ["-y", "@notharshhaa/devops-mcp@latest"],
      "env": {
        "KUBECONFIG": "/home/you/.kube/config",
        "ARGOCD_SERVER": "https://argocd.company.com",
        "ARGOCD_TOKEN": "your-argocd-token",
        "PROMETHEUS_URL": "http://prometheus.monitoring:9090",
        "PAGERDUTY_TOKEN": "your-pd-api-token",
        "LOKI_URL": "http://loki.monitoring:3100",
        "LOKI_TOKEN": "your-loki-token"
      }
    }
  }
}

Restart Claude Desktop. The devops server will appear in the tools list.

Claude Code (CLI)

claude mcp add devops-mcp -e KUBECONFIG=$HOME/.kube/config \
  -e ARGOCD_SERVER=https://argocd.company.com \
  -e ARGOCD_TOKEN=... \
  -e PROMETHEUS_URL=http://prometheus:9090 \
  -e PAGERDUTY_TOKEN=... \
  -e LOKI_URL=http://loki.monitoring:3100 \
  -e LOKI_TOKEN=... \
  -- npx -y @notharshhaa/devops-mcp@latest

Local dev / test

Requires Node.js 20 or newer.

npx @notharshhaa/devops-mcp
# or clone and run:
git clone https://github.com/NotHarshhaa/devops-mcp
cd devops-mcp
npm install
cp .env.example .env   # fill in your values
npm run dev

Configuration

All config is via environment variables. Only set the ones for providers you actually use — providers with missing config are silently skipped.

# ── Kubernetes ────────────────────────────────────────────────
KUBECONFIG=/home/user/.kube/config       # omit to use in-cluster service account
K8S_CONTEXT=my-prod-context              # optional: pin a specific context
K8S_ALLOWED_NAMESPACES=default,backend   # optional: restrict namespace access

# ── ArgoCD ───────────────────────────────────────────────────
ARGOCD_SERVER=https://argocd.company.com
ARGOCD_TOKEN=eyJhbGci...                 # argocd account generate-token

# ── Prometheus ───────────────────────────────────────────────
PROMETHEUS_URL=http://prometheus:9090
PROMETHEUS_BEARER_TOKEN=                 # optional: for authenticated Prometheus

# ── PagerDuty ────────────────────────────────────────────────
PAGERDUTY_TOKEN=your-api-v2-token

# ── Loki ───────────────────────────────────────────────────
LOKI_URL=http://loki.monitoring:3100
LOKI_TOKEN=your-loki-token

# ── Stateless Streamable HTTP ────────────────────────────────
# For stdio mode (default): no transport config needed
MCP_HTTP_HOST=127.0.0.1                 # use 0.0.0.0 inside a container
PORT=3000
MCP_AUTH_TOKEN=shared-secret            # optional static Bearer token
MCP_REQUEST_STATE_SECRET=32+-byte-secret # optional MRTR signing key shared by all replicas
MCP_ALLOWED_HOSTS=localhost,127.0.0.1   # required with non-loopback binding
MCP_ALLOWED_ORIGINS=                    # optional browser Origin hostname allowlist
MCP_CACHE_TTL_MS=60000                  # discovery/tools catalog TTL; 0 disables caching

# ── Safety ───────────────────────────────────────────────────
DEVOPS_MCP_DRY_RUN=false                # true = block all mutations globally
DEVOPS_MCP_AUDIT_LOG=/var/log/devops-mcp-audit.jsonl

Tool reference

All tools follow a three-tier safety model:

• Read — safe, no side effects, no confirmation needed
• Mutate — defaults to dry_run: true; set dry_run: false to execute
• Destructive — requires confirm: true, or a 2026-07-28 client can complete the server's interactive MRTR confirmation

Kubernetes (k8s__*)

ArgoCD (argo__*)

Prometheus (prom__*)

Example usage:

# Get a human-readable health summary
prom__summarize_service_health(service="payments", timeframeMinutes=30, sloThreshold=0.05)

What it outputs:

• Latency: "Latency increased: 120ms → 480ms (+300%)" or "Latency stable: 125ms"
• Error rate: "Error rate crossed SLO (5%): 7.2%" or "Error rate within SLO: 2.1%"
• Traffic: "Traffic dropped: 500 → 350 req/s (-30%)" or "Traffic spike detected (+150%)"
• Overall assessment: Summary of issues and positive indicators

Why this matters: Instead of raw PromQL numbers that require interpretation, this tool provides actionable insights that AI agents can use directly in responses, making monitoring data actually useful for incident investigation and communication.

Loki (logs__*)

Example usage:

# Get recent error logs
logs__get_recent_errors(service="payments", namespace="default", minutes=30, limit=50)

# Search logs with custom query
logs__search(query='{service="payments"} |= level="error"', limit=100)

Why this matters:

• Metrics tell what: Prometheus shows you that latency increased or error rate crossed SLO
• Logs tell why: Loki shows you the actual error messages, stack traces, and context around failures
• Complete debugging: Without logs, you can see that something is broken but not understand the root cause

Output format:

• Structured log entries with timestamp, message, service, namespace, and extracted log levels
• Error count summaries and filtering
• Raw LogQL results for detailed analysis

This makes incident investigation complete by combining the "what" (metrics) with the "why" (logs).

PagerDuty (pd__*)

pd__summarize_incident

Example usage:

# Get an auto-summary of an incident
pd__summarize_incident(id="ABC123")

What it outputs:

• What happened: Incident title, description, severity, urgency, status, creation time, and duration
• Affected services: Service name, ID, and current status
• Probable root cause: Analysis of trigger alerts and log entries to identify likely causes
• Current status: Current incident state, assignees, acknowledgements, and notes count

Output format:

{
  "what_happened": {
    "title": "API Gateway High Error Rate",
    "description": "5xx error rate exceeded 5% threshold",
    "severity": "high",
    "urgency": "high",
    "status": "acknowledged",
    "createdAt": "2025-01-15T10:30:00Z",
    "updatedAt": "2025-01-15T11:45:00Z",
    "duration": "1h 15m"
  },
  "affected_services": [
    {
      "id": "P123456",
      "name": "API Gateway",
      "status": "critical"
    }
  ],
  "probable_root_cause": "Triggered by: High 5xx error rate from API Gateway pods",
  "current_status": {
    "status": "acknowledged",
    "lastUpdated": "2025-01-15T11:45:00Z",
    "assignees": ["john.doe@company.com"],
    "acknowledgements": 2,
    "notes": 3
  }
}

Why this matters: Instead of manually piecing together incident details from multiple API calls, this tool provides a comprehensive, human-readable summary perfect for:

• Demos: Shows AI's ability to understand and summarize complex incident data
• Real-world use: Quickly understand incident impact without digging through raw data
• Communication: Share concise incident summaries with stakeholders

Helm (helm__*)

Requirements: Helm CLI binary must be available in PATH.

Example usage:

# List all releases in a namespace
helm__list_releases(namespace="production")

# Check what values a release is using
helm__get_values(name="api-gateway", all_values=true)

# Rollback after a bad deploy
helm__rollback(name="api-gateway", revision=5, dry_run=false)

Cross-Provider Debugging (devops__*)

devops__debug_service

Example usage:

# Debug a service across all providers
devops__debug_service(service="payments", namespace="default")

What it checks:

• Kubernetes: Pod status, restart counts, readiness, deployment health, recent events
• ArgoCD: Sync status, health status, Git diff detection, deployment history
• Prometheus: Error rate (5xx responses), latency (p95), firing alerts
• PagerDuty: Active incidents matching the service name

Output format:

• Human-readable diagnosis with emoji indicators (⚠️ warnings, ❌ errors)
• Per-provider status sections
• Summary highlighting critical issues
• Raw JSON data for detailed analysis

This is the most powerful tool for incident investigation - it gives you a complete picture of what's wrong with a service in seconds.

devops__explain_change

Example usage:

# Explain what changed in the last hour
devops__explain_change(service="payments", namespace="default", timeframeMinutes=60)

What it analyzes:

• ArgoCD: Deployment history within the timeframe, including revision, author, repo, and chart
• Kubernetes: Current rollout status, replica counts, image tags, and deployment readiness
• Prometheus: Error rate trends, latency patterns, and traffic spikes over the time window

Output format:

• Timeline of recent deployments with full metadata
• Kubernetes rollout status and health
• Metric anomaly detection (error rate spikes, latency issues, traffic changes)
• Correlation analysis that links deployments to metric changes
• Summary with root cause hypothesis

Problem it solves: "Everything was working yesterday… what changed?"

This tool answers that question by correlating deployment events with metric anomalies, helping you quickly identify whether a recent deployment, config change, or external factor caused the issue.

devops__runbook

Example usage:

# Diagnose a crashlooping service
devops__runbook(symptom="crashloop", service="payments", namespace="default")

# Investigate high latency
devops__runbook(symptom="high-latency", service="api-gateway")

Supported symptoms:

Output: Structured JSON with steps_executed[], findings[], and recommended_actions[].

devops__health_report

Example usage:

# Get a full cluster health assessment
devops__health_report(namespace="production")

What it gathers:

• Kubernetes: Unhealthy pods, deployments not at desired replicas
• Prometheus: Count of firing alerts
• ArgoCD: Out-of-sync and unhealthy applications
• PagerDuty: Open incident count

Output: Overall status (healthy / degraded / critical), per-provider sections, and summary. Perfect for morning standup checks or shift handoffs.

Deployment options

stdio (recommended for local use)

The MCP host launches devops-mcp as a subprocess and communicates over stdin/stdout. Zero network config. Auth comes from the local environment (kubeconfig, env vars). Process lifecycle tied to Claude Desktop.

npx @notharshhaa/devops-mcp
# or with env vars
KUBECONFIG=~/.kube/config npx @notharshhaa/devops-mcp

Stateless Streamable HTTP (shared deployments)

The HTTP entry serves MCP at POST /mcp using the 2026-07-28 stateless protocol. Each request gets a fresh MCP server instance, so requests can land on any replica without session affinity or shared protocol state. The same endpoint also accepts 2025-era Streamable HTTP clients in stateless compatibility mode.

MCP_HTTP_HOST=127.0.0.1 \
PORT=3000 \
MCP_AUTH_TOKEN=your-secret \
npx -y -p @notharshhaa/devops-mcp@latest devops-mcp-http

Connect clients to http://127.0.0.1:3000/mcp. For a container or remote service, set MCP_HTTP_HOST=0.0.0.0 and configure MCP_ALLOWED_HOSTS with the public/proxy hostnames. Put the service behind TLS for team use.

The deprecated devops-mcp-sse binary remains as a temporary alias for the HTTP entry, but /sse, /message, and /ws now return HTTP 410. Legacy HTTP+SSE and non-standard WebSocket clients must migrate to Streamable HTTP.

2026-07-28 behavior

• No initialize requirement or Mcp-Session-Id on modern requests.
• server/discover, per-request client metadata, and MCP-Protocol-Version are handled by the official SDK.
• Mcp-Method and Mcp-Name headers are validated against the JSON-RPC body for gateway routing and authorization.
• server/discover and tools/list advertise deterministic, public cache hints using MCP_CACHE_TTL_MS (default 60 seconds).
• Destructive tools accept confirm: true; modern clients may instead complete an MRTR interactive confirmation. Confirmation state is HMAC-signed, expires after five minutes, and is bound to the exact tool arguments. Global dry-run blocks before prompting.
• MCP_REQUEST_STATE_SECRET must be the same on every replica for MRTR retries to land anywhere. When omitted, the server derives the key from MCP_AUTH_TOKEN, or uses a process-local random key when no token is configured.
• 2025-era Streamable HTTP and stdio clients remain supported. Sessionful HTTP and legacy HTTP+SSE are not.

The built-in MCP_AUTH_TOKEN is a static bearer-token gate, not an OAuth authorization server. For Internet-facing deployments, terminate TLS and enforce your organization’s OAuth/OIDC policy at a gateway or integrate a dedicated identity provider; do not use deprecated Dynamic Client Registration for new deployments.

A minimal docker-compose.yml is available in examples/.

Security model

devops-mcp is designed for internal use inside a trusted network. That said:

• Kubernetes: Uses standard kubeconfig via @kubernetes/client-node. Supports exec plugins (AWS EKS, GKE). In-cluster: auto-mounts SA token. Add RBAC rules scoped to your desired permissions — run devops-mcp under a dedicated ServiceAccount with minimal verbs. Context selection is fixed by K8S_CONTEXT at startup; the tool only previews changes because runtime switching would affect other callers.
• ArgoCD: Generate a long-lived token: argocd account generate-token --account devops-mcp. Create a dedicated account in argocd-cm with apiKey capability and a role limited to read + sync.
• Prometheus: Usually unauthenticated inside a cluster. If using Grafana Mimir or Thanos with auth, pass a Bearer token. All tools are read-only so minimal permissions are needed.
• PagerDuty: Create a dedicated API key in PagerDuty → API Access → Create New API Key. Use Full Access if you want acknowledge/escalate tools; Read-only if you want a safe-only mode.
• Mutations are dry-run by default. Every mutating tool defaults dry_run: true. The AI must explicitly pass dry_run: false — it won't do this unless the user clearly requests an action.
• Destructive tools require confirmation. Pass confirm: true directly, or use a 2026-07-28 client that supports the server's MRTR confirmation request. DEVOPS_MCP_DRY_RUN=true blocks execution even after confirmation.
• Audit log. Set DEVOPS_MCP_AUDIT_LOG to a file path. Every tool call is written as a JSONL line with timestamp, tool name, parameters, and outcome. Mutations and destructive calls are flagged.
• Global dry-run mode. Set DEVOPS_MCP_DRY_RUN=true to block every executing mutation, even when a caller passes dry_run: false. Safe previews remain available — useful for read-only team deployments.

Architecture

Client / UI agents (Claude Desktop, Claude Code, gateways)
       │
       ▼
  MCP v2 Serving Layer
  ┌──────────────────────────────────────────┐
  │ serveStdio       │ POST /mcp             │
  │ 2025 + 2026 eras │ stateless per request │
  │                  │ routing/header checks │
  └──────────────────────────────────────────┘
       │
       ▼
  Server Factory & Tool Registry
  ┌──────────────────────────────────────────┐
  │ Fresh protocol instance per HTTP request │
  │ Deterministic tool catalog + cache hints │
  │ MRTR confirmation for destructive tools │
  │ Audit logging and error normalization    │
  └──────────────────────────────────────────┘
       │
       ▼
  ┌─────┬──────┬──────┬──────┬──────┬──────┐
  k8s   argo   prom   pd     logs   helm
       │
       ▼
  Dry-run guard │ Namespace policy │ Provider credentials

Key architectural features:

• Stateless remote protocol: each /mcp request creates a fresh server instance; no protocol session ID or sticky load balancing.
• Dual-era compatibility: official SDK entries serve 2026-07-28 and compatible 2025-era stdio/Streamable HTTP clients.
• Gateway-friendly routing: modern method and tool headers are validated before dispatch.
• Safe caching: deterministic tools/list ordering and configurable public cache hints.
• Provider isolation: each provider remains independently configured and safely skipped when unavailable.

Contributing

Contributions are welcome. The most useful areas:

• New providers — Grafana, Datadog, Vault, Terraform Cloud, Flux CD
• New tools — within existing providers (e.g. k8s__get_node_pressure, argo__get_app_logs)
• Better output formatting — richer structured responses for specific resource types
• Tests — unit tests for provider logic using mocked clients

Adding a new provider

1. Create src/providers/yourprovider/ with index.ts, client.ts, and one file per resource group.
2. Register it in src/server.ts.
3. Add config keys to .env.example and src/config.ts.
4. Document tools in this README following the existing table format.
5. Open a PR.

Local development

git clone https://github.com/NotHarshhaa/devops-mcp
cd devops-mcp
npm install
cp .env.example .env
npm run dev        # tsx watch — restarts on file change

Run against a local kind/minikube cluster for Kubernetes testing. Use DEVOPS_MCP_DRY_RUN=true to prevent accidental mutations during development.

Roadmap

• Grafana provider (grafana__*) — dashboards, annotations, datasources
• Flux CD provider (flux__*) — kustomizations, helm releases, image automation
• Terraform Cloud provider (tfc__*) — workspace runs, state, variables
• HashiCorp Vault provider (vault__*) — secret read (never write), lease status
• Datadog provider (dd__*) — metrics, monitors, events
• Web UI for provider health, task progress, and audit events

License

MIT — see LICENSE.

Built for DevOps and platform engineers who want AI that actually knows what's happening in their cluster.