# observability-mcp

An observability gateway for AI agents that connects Prometheus, Loki, and topology tools through a single interface for incident triage.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 7
- Author: ThoTischner
- License: Apache-2.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/ThoTischner/observability-mcp
- Updated: 2026-10-19
- HTML: https://affpapa.org/en/nevibecode/mcp/observability-mcp

## What it does

The server acts as a middle layer connecting AI agents to monitoring platforms like Prometheus and Loki. Instead of returning raw log dumps, the gateway filters and aggregates data on the server side. The agent receives clean summaries.

Specialized inspection calls like `get_topology` and `get_blast_radius` resolve dependencies between pods and cluster nodes. Every tool runs in read-only mode. That prevents the model from altering runtime infrastructure.

At startup, the gateway has zero configured backends. You configure data sources either through the browser UI on port `3000` or with `PROMETHEUS_URL` and `LOKI_URL` environment variables. Without those backends in place, the gateway cannot collect incident metrics.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `MCP_TRANSPORT`, `PROMETHEUS_URL`, `LOKI_URL` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env MCP_TRANSPORT=<MCP_TRANSPORT> --env PROMETHEUS_URL=<PROMETHEUS_URL> --env LOKI_URL=<LOKI_URL> --transport stdio observability-mcp -- npx -y @thotischner/observability-mcp
```
Replace <…> with your own values

### Codex

**Platform CLI**
```bash
codex mcp add observability-mcp --env MCP_TRANSPORT=<MCP_TRANSPORT> --env PROMETHEUS_URL=<PROMETHEUS_URL> --env LOKI_URL=<LOKI_URL> -- npx -y @thotischner/observability-mcp
```
Replace <…> with your own values

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "observability-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "@thotischner/observability-mcp"
            ],
            "env": {
                "MCP_TRANSPORT": "<MCP_TRANSPORT>",
                "PROMETHEUS_URL": "<PROMETHEUS_URL>",
                "LOKI_URL": "<LOKI_URL>"
            }
        }
    }
}
```
Replace <…> with your own values

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "observability-mcp": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "@thotischner/observability-mcp"
            ],
            "env": {
                "MCP_TRANSPORT": "<MCP_TRANSPORT>",
                "PROMETHEUS_URL": "<PROMETHEUS_URL>",
                "LOKI_URL": "<LOKI_URL>"
            }
        }
    }
}
```
Replace <…> with your own values

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e MCP_TRANSPORT=<MCP_TRANSPORT> -e PROMETHEUS_URL=<PROMETHEUS_URL> -e LOKI_URL=<LOKI_URL> observability-mcp npx -y @thotischner/observability-mcp
```
Replace <…> with your own values

## When to use it
- map co-located pods on a failing cluster node
- query Prometheus metrics with server-side aggregation
- calculate blast radius during a service outage
- inspect infrastructure topology using read-only agent tools

## Example prompts
- Run `get_blast_radius` on `payment-service` to see what pods share the node.
- Check `get_topology` to find dependent services before restarting the deployment.

## Similar
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33989
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81163
- [Oh My Posh Validator](https://affpapa.org/en/nevibecode/mcp/oh-my-posh-validator.md) — MCP server · ★ 23654
- [Keploy](https://affpapa.org/en/nevibecode/mcp/keploy.md) — MCP server · ★ 18779
- [Coder](https://affpapa.org/en/nevibecode/mcp/coder.md) — MCP server · ★ 17191
- [mcp](https://affpapa.org/en/nevibecode/mcp/kubeshark-mcp.md) — MCP server · ★ 12110

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md