observability-mcp

npx @thotischner/observability-mcp                                    # start (UI on :3000)
claude mcp add observability --transport http http://localhost:3000/mcp   # wire into Claude

十二个只读工具（每个工具均设置 readOnlyHint: true） · 服务端筛选/聚合， 让 Agent 获取数字，而非海量杂乱数据 · 面向 Agent 的指南

---

📖 完整文档网站： https://thotischner.github.io/observability-mcp/

🔌 在 MCP Inspector 中打开 — 单行交互式浏览器：

npx --yes @modelcontextprotocol/inspector \
  --config <(npx --yes @thotischner/observability-mcp inspector-config)

为什么重要——以实测为准，而非口头断言

针对一个真实的 Kubernetes 平台团队问题（“哪些其他 Pod 与 payment-service 共用同一个节点？这样我们就知道节点宕机时还会影响什么？”），同一个本地模型会根据提供给它的工具，给出截然不同的答案：

Agent 可用的工具（llama3.1:8b，n=10）	跨命名空间故障影响范围准确率
通用指标 + 日志 + 服务工具	0 / 10  — 幻觉出错误的实体类型（prometheus、loki、kubernetes）
同一模型 + get_topology + get_blast_radius	10 / 10  — 每次迭代都准确列出共用租户列表

两组测试的原始 JSON，以及另外三个场景（单服务根因分析、命名空间内故障影响范围、拓扑无帮助的场景），见 docs/benchmark-astronomy-shop.md。测试框架位于 scripts/benchmark-rca.mjs；运行 make benchmark-up && make benchmark-run 可重新测试。

我们不宣称性能总能提升——文档明确说明了拓扑工具在哪些情况下有帮助（图结构问题），以及在哪些情况下没有帮助（纯单指标下钻）。

---

10 秒上手

npx @thotischner/observability-mcp
# then open http://localhost:3000

用一条 CLI 命令将它接入 Claude Code：

claude mcp add observability --transport http http://localhost:3000/mcp

……或者将它提交到你的代码仓库，作为 .mcp.json（在 Claude Desktop / Cursor 中效果相同）：

{
  "mcpServers": {
    "observability": {
      "transport": { "type": "http", "url": "http://localhost:3000/mcp" }
    }
  }
}

服务启动时没有任何数据源。通过 Web UI 或 PROMETHEUS_URL / LOKI_URL 环境变量添加 Prometheus/Loki。

如果你希望通过 Make 目标输出上面的代码片段——包括替换自定义主机 / 端口——请使用 make connect-claude-code 或 make connect-cursor。make doctor 会对运行中的服务执行真实的 MCP 握手，报告当前治理状态（身份验证模式、脱敏、审计日志持久化、每个身份的速率上限），并在失败时告知需要修复的内容。

多用户 / 生产环境？ 请参阅 docs/access-control.md 了解启用基本模式登录 + RBAC + 审计日志 + 每身份速率限制的设置。 默认全部关闭；上述演示不受影响。

通过 OIDC 实现 SSO？ make demo-oidc 会启动 Keycloak 和一个采用 OIDC 的 mcp-server，运行在端口 3001，并预置三个用户 （admin / operator / viewer，密码 = 用户名，仅供演示）。 生产环境中的 Keycloak / Authentik / Auth0 / Azure AD 设置请参阅 docs/auth-oidc.md。

通过 OPA 实现外部 RBAC？ make demo-opa 会启动 Open Policy Agent， 并加载示例 Rego 策略和一个由 OPA 提供支持的 mcp-server，运行在端口 3002。 内置 / 文件 / OPA 后端的权衡与迁移路径请参阅 docs/policy-engines.md。

精选的 MCP 产品？ 将 OMCP_PRODUCTS_FILE 设置为 YAML 目录 （config/products.yaml.example）， 并按租户 / Agent 分发工具包，而不是“始终提供所有工具”。受 RBAC 控制、可审计、支持热编辑。详情见 docs/products.md。

想要体验完整的混沌工程演示（Prometheus + Loki + 3 个示例服务 + 自主 Agent）？克隆并运行：

make demo   # equivalent to: docker compose --profile demo up --build --wait

或者运行主权快速入门——一条命令，全程本地运行，不进行任何外部调用：它会启动整个技术栈、注入真实故障，并并排展示 Agent 在没有和有分析层时分别能获得什么（满屏原始数字，还是能精准定位问题根因的评分结论）。可选的 Agent 会使用本地模型（Ollama）进行推理：

make demo-sovereign

所有标准工作流请参阅 make help。

为什么？

每家可观测性厂商都提供自己的 MCP 服务——Prometheus、Grafana、Datadog、Elastic，各自形成孤岛。AI Agent 在跨系统处理事件时，必须同时协调 N 个独立服务，并学习每种查询语言（PromQL、LogQL 等）。目前没有统一的抽象层。

observability-mcp 就是这一层：通过一个 MCP 端点统一各个后端，并用通俗的服务、指标和日志术语作答；此外，它还配备分析引擎，可标记异常，避免 Agent 必须自行从原始查询中重建异常情况。

适用对象： 使用 Prometheus + Loki，并借助 AI Agent（Claude、本地大模型等）处理事件的 SRE / 平台团队。当 Agent 不是前沿模型时，网关的价值最大——规模较小或本地运行、无法可靠地手写 PromQL/LogQL 的模型，最能受益于标准化工具和预计算分析。能力强大的前沿模型可以独立熟练地查询原始后端；在这种情况下，价值在于一致性和分析引擎，而非查询便利性。我们如实说明这一点，而不宣称普遍提速。

功能

• 🔍 检视 — 查看、了解并约束 Agent 行为 — 实时展示每次 MCP 工具调用的服务网格风格图谱；提供类似 AppArmor 的学习工作流，根据真实流量生成行为配置文件；还提供执行模式，可阻止超出已接受基线的调用。跳转到“检视” ↓
• 统一网关 — 通过单个 MCP 端点接入所有可观测性后端。
• 跨信号分析 — 自动关联指标和日志。提供稳健的异常检测（中位数/MAD 基线、慢速爬升趋势检测、预热 + 驻留机制以抑制抖动）和加权健康评分。
• Web 界面 — 管理数据源、服务、健康监控和配置。实时更新，采用深色主题。
• prom-client 默认配置 — 开箱即用，兼容标准的 Node.js Prometheus 插桩。动态标签解析会探测 job / service / app / service_name，让服务筛选直接可用。
• Loki 标签回退 — 通过 service_name / service / job / app / container 发现服务，也能识别带有前导斜杠的 Docker 推送流。
• 可插拔连接器 — 一套接口，支持任意查询语言（PromQL、LogQL、Flux、KQL 等）。参见 docs/connectors.md。
• 身份验证与 TLS — 支持 Basic、Bearer、自定义 CA 和 mTLS。参见 docs/auth-and-tls.md。
• 多后端 — 可配置同类型的多个实例。

Inspect — 查看、学习并约束 Agent 行为

你把观测后端的密钥交给了一个 Agent（或 CI 机器人，或泄露的凭证）。Inspect 回答了 RBAC 无法回答的问题：与该身份实际执行过的操作相比，这次调用是否正常？

它借鉴了 AppArmor 的学习工作流和服务网格流量视图（可以把 Kiali 想象成面向 Agent 工具调用的流量视图）：

   OFF  ──▶  OBSERVE  ──▶  DRY-RUN (complain)  ──▶  ENFORCE
              │              │                        │
        record calls    compute what WOULD be     block calls that
        only (zero      blocked, but still allow   fall outside the
        risk, default)  — review before enforcing   accepted profile

• 流量 — 实时的 身份 → 工具 → 后端 图。边的粗细表示调用量；颜色表示允许 / 偏离 / 阻止。点击任意节点即可深入查看实际调用、参数形态分布，并直接将观测到的边转换为规则。
• 配置文件 — 学习循环：点击 “从流量学习”，查看建议的规则（anonymous → query_logs · service ∈ {payment-service} — 从 N 次调用中学习得出），然后逐条接受 / 编辑 / 拒绝。只有已接受的规则才会对流量进行管控。
• 偏离 — 每次超出配置文件范围的调用：谁调用、使用了哪个工具、异常之处是什么——点击一次即可将其纳入配置文件，或确认为异常。

隐私保护从设计开始：Inspect 仅存储参数的形态，绝不存储原始负载；并且会先通过网关的脱敏层处理所有内容。它不会发起任何出站调用——隔离网络保障不变。

开源版与授权版：observe 和 dry-run——实时图、学习配置文件、查看本会被阻止的偏离——免费。主动 enforce 阻止属于需授权的管控功能（在界面中以 🔒 标示）。可见性免费；强制执行是授权功能。完整设计： docs/inspect.md。

检测质量

异常检测引擎通过带标签的合成测试集进行回测，涵盖缓慢爬升（内存泄漏直至 OOM）、峰值、阶跃变化、稳定噪声、瞬时波动、单侧恢复、每日季节性模式，以及刻意设置的低信噪比“困难”级别。回测评分作为 CI 门禁（backtest.test.ts）——这些数字由该测试集重新生成，并非手工编写：

案例数	精确率	召回率	F1
64	100.0%	87.5%	93.3%

精确率为 100%（没有误报）；未召回的案例是设计所致，处于困难级别的噪声下限。测试集具有确定性，检测器回归会导致 CI 失败。可在本地复现：

docker run --rm -w /app -v "$(pwd)/mcp-server:/app" node:22-alpine \
  sh -c "npm i --silent && npx tsx --test src/analysis/backtest.test.ts"

截图

Inspect — 流量图	Inspect — 学习配置文件

仪表板	服务健康状态	连接器中心

架构

graph TB
    Agent["AI Agent<br/><small>Claude, Ollama, etc.</small>"]

    subgraph MCP ["observability-mcp :3000"]
        Tools["12 MCP Tools"]
        Analysis["Analysis Engine<br/><small>Robust stats, Health Scoring, Correlation</small>"]
        UI["Web UI"]
    end

    subgraph Connectors ["Pluggable Connectors"]
        Prom["Prometheus<br/><small>PromQL — metrics</small>"]
        Loki["Loki<br/><small>LogQL — logs</small>"]
        K8s["Kubernetes<br/><small>watch — topology</small>"]
        Next["Your Backend<br/><small>Any query language</small>"]
    end

    Agent <-->|"MCP<br/>Streamable HTTP"| Tools
    Tools --- Analysis
    Tools --- UI
    MCP --> Prom & Loki & K8s & Next

    style MCP fill:#1a1a2e,stroke:#58a6ff,color:#fff
    style Connectors fill:#0d1117,stroke:#3fb950,color:#fff
    style Agent fill:#58a6ff,stroke:#58a6ff,color:#000
    style Next fill:#0d1117,stroke:#3fb950,color:#8b949e,stroke-dasharray: 5 5

仓库结构

mcp-server/   # the product — server, Web UI, analysis engine, built-in plugins
helm/         # ArtifactHub-grade Helm chart
docs/         # configuration, auth, plugin architecture, airgapped deployment, ...
examples/     # demo material — agent, example services, Prometheus+Loki configs

mcp-server/ 是需要安装的内容。examples/ 下的所有内容都通过 docker compose --profile demo 选择性启用——它用于展示仓库如何端到端演示混沌检测，但生产部署不需要其中任何内容。

安装

方式	命令	适用场景
npm	npx @thotischner/observability-mcp	本地开发、Node 工具链、无需安装
Docker (GHCR)	docker run -p 3000:3000 ghcr.io/thotischner/observability-mcp:latest	生产主机、隔离环境
Helm	helm repo add observability-mcp https://thotischner.github.io/observability-mcp/ helm install observability-mcp observability-mcp/observability-mcp	Kubernetes
从源码构建	git clone … && make demo	完整 POC，包含示例服务和故障注入
CLI (omcp)	npm i -g @thotischner/observability-mcp	在终端管理连接器、演示堆栈和 Helm——参见 CLI

GHCR 支持多架构（amd64 + arm64）。可用标签：latest、main、X.Y.Z、X.Y、X、sha-<commit>。注意：语义化版本标签开头的 v 会被去除。

Helm chart

该 chart 包含 Deployment、Service、可选的 Ingress/PVC/HPA、NetworkPolicy、ServiceMonitor（自动检测 Prometheus Operator CRD 并启用）、helm test 连接探测，以及 values.schema.json 验证。带有符合 ArtifactHub 标准的注解。完整的 values 参考请参见 helm/observability-mcp/，或参见隔离网络部署指南了解经过加固的生产环境示例。

helm repo add observability-mcp https://thotischner.github.io/observability-mcp/
helm repo update
helm install observability-mcp observability-mcp/observability-mcp \
  --set sources.prometheusUrl=http://prometheus.monitoring.svc.cluster.local:9090 \
  --set sources.lokiUrl=http://loki.logging.svc.cluster.local:3100

# docker-compose snippet
services:
  observability-mcp:
    image: ghcr.io/thotischner/observability-mcp:latest
    ports: ["3000:3000"]
    environment:
      PROMETHEUS_URL: http://prometheus:9090
      LOKI_URL: http://loki:3100
    volumes:
      - ./mcp-config:/home/node/.observability-mcp
    restart: unless-stopped

完整配置说明——包括路径、环境变量、${VAR} 替换和完整的 sources.yaml 参考——请参见 docs/configuration.md。

快速开始

选项 A：独立运行（使用你自己的后端）

npx @thotischner/observability-mcp

然后在浏览器中打开 Web UI：http://localhost:3000，点击 Sources → + Add Source，填入你的 Prometheus/Loki URL。也可以跳过 UI：

PROMETHEUS_URL=http://localhost:9090 LOKI_URL=http://localhost:3100 \
  npx @thotischner/observability-mcp

选项 B：Grafana Cloud

Grafana Cloud 使用 Basic Auth，用户名为数字实例 ID，密码为 API token。Prometheus 和 Loki 的实例 ID 不同——可在 Connections → Data sources 中找到两者。

# ~/.observability-mcp/sources.yaml
sources:
  - name: grafana-cloud-prom
    type: prometheus
    url: https://prometheus-prod-XX-prod-eu-west-X.grafana.net/api/prom
    enabled: true
    auth:
      type: basic
      username: "${GRAFANA_PROM_USER}"   # numeric instance ID
      password: "${GRAFANA_TOKEN}"
  - name: grafana-cloud-loki
    type: loki
    url: https://logs-prod-XXX.grafana.net
    enabled: true
    auth:
      type: basic
      username: "${GRAFANA_LOKI_USER}"   # different from Prom!
      password: "${GRAFANA_TOKEN}"

GRAFANA_PROM_USER=… GRAFANA_LOKI_USER=… GRAFANA_TOKEN=glc_… \
  npx @thotischner/observability-mcp

选项 C：完整演示（使用示例服务的 Docker Compose）

git clone https://github.com/ThoTischner/observability-mcp.git
cd observability-mcp
docker compose --profile demo up --build

启动单节点 k3s 集群，构建三个示例服务，并在 k3s 中将它们作为 Kubernetes Deployments 运行，同时在 docker-compose 侧运行 Prometheus、Loki、Promtail、MCP 服务和 Agent。打开 http://localhost:3000。

Prometheus 抓取指标、Loki 接收日志的同一批 Deployments 也会显示在拓扑图中，因此 Agent 可以使用 get_blast_radius 将指标/日志异常与底层主机相关联。故障注入端点仍位于 localhost:8080/8081/8082（映射到 k3s NodePorts），现有脚本和演示视频无需修改即可继续使用。

不使用 --profile demo 时，只会启动 mcp-server——适用于你已在其他位置运行 Prometheus/Loki，只想通过 MCP 暴露它们的情况。

选项 D：基准测试模式（OpenTelemetry Demo / Astronomy Shop）

针对真实微服务工作负载（约 23 个服务，使用原生 OTel 插桩）生成可信的 RCA 数据：

make benchmark-up         # clones upstream Astronomy Shop, brings up both stacks
make benchmark-run        # runs the harness baseline vs topology, writes JSON
make benchmark-down       # tears down

make benchmark-up 会在我们的 --profile benchmark 下添加 Tempo 和 OTel collector 桥接器，并在单独的 compose 项目中编排上游堆栈，将其网络连接到我们的网络，使 Astronomy Shop 服务能够向我们的 Tempo 推送追踪数据。请参见 docs/benchmark-astronomy-shop.md 和 examples/benchmark/README.md。首次拉取约需 4 GB。

MCP 工具

工具	信号	用途
list_sources	meta	发现已配置的后端及连接状态
list_services	meta	发现所有后端中受监控的服务
query_metrics	metrics	查询指标并获取预先计算的摘要统计信息
query_logs	logs	查询日志并获取错误／警告数量及主要模式
get_service_health	unified	综合指标与日志得出的健康评分（0–100）
detect_anomalies	unified	跨信号异常检测，采用稳健分析方法（中位数／MAD + 趋势）
get_topology	topology	返回所有支持拓扑的连接器合并后的基础设施图（资源 + 边），可按来源／类型／范围筛选
get_blast_radius	topology	基于通用的 RUNS_ON 关系进行追溯——“如果该资源所在的主机发生故障，还有哪些资源会受影响？”。适用于 pod→node、vm→hypervisor、container→host

这两个拓扑工具需要支持拓扑的连接器。随附的 Kubernetes connector 是第一个；未来的连接器（vCenter、NetBox、……）可通过相同的 isTopologyProvider 接口接入，并从规范的拓扑词汇表中输出 kind／relation 值。

与 Claude Code 搭配使用

直接连接 Claude Code——无需 Agent。

命令行：

claude mcp add observability --transport http http://localhost:3000/mcp

或者在项目根目录使用 .mcp.json（便于提交到版本控制）：

{
  "mcpServers": {
    "observability": {
      "transport": { "type": "http", "url": "http://localhost:3000/mcp" }
    }
  }
}

然后用自然语言向 Claude 提问。例如，在演示中触发混沌故障后（curl -X POST http://localhost:8081/chaos/error-spike）：

“现在有异常吗？”

Claude 调用 detect_anomalies 并发现：

{
  "anomalies": [
    { "metric": "cpu", "severity": "high", "service": "payment-service",
      "description": "cpu is 3.4σ above baseline (18.36 → 37.31)" },
    { "metric": "request_rate", "severity": "low", "service": "payment-service",
      "description": "request_rate is -1.8σ below baseline (0.08 → 0.04)" }
  ]
}

“给我看看 payment-service 的错误日志。”

Claude 调用 query_logs：

{
  "summary": {
    "total": 11, "errorCount": 11,
    "topPatterns": [
      "Request failed: internal error during POST /payments (6x)",
      "Request failed: internal error during POST /refunds (4x)"
    ]
  }
}

Claude 将这些信号关联起来——CPU 飙升、错误日志激增、请求速率减半——并用通俗易懂的语言说明事故情况。无需 PromQL，也无需 LogQL。

演示：混沌工程

三个示例微服务会生成流量并支持注入混沌故障：

curl -X POST http://localhost:8081/chaos/high-cpu        # CPU spike
curl -X POST http://localhost:8081/chaos/error-spike     # CPU + latency + errors
curl -X POST http://localhost:8081/chaos/slow-responses  # Latency
curl -X POST http://localhost:8081/chaos/memory-leak     # OOM logs
curl -X POST http://localhost:8081/chaos/reset

Agent（docs/agent.md）会在 30 秒内检测到异常；如果 Ollama 正在运行，还会生成由大模型撰写的事故分析。

命令行（omcp）

同一个 npm 包（omcp bin）中附带了一个控制命令行工具，可用于管理连接器、演示环境和 Helm 安装。

安装它（或无需安装，直接临时运行）：

npm i -g @thotischner/observability-mcp   # puts `omcp` on your PATH
omcp --help

# or, no install:
npx -p @thotischner/observability-mcp omcp doctor

然后：

omcp doctor                       # check docker / compose / helm / node
omcp demo up                      # full demo stack (auto-picks free host ports)
omcp plugin list                  # browse the connector hub catalog
omcp plugin install [email protected] --trust-root key.pem    # download + verify + extract
omcp plugin verify ./plugins/tempo --trust-root key.pem # offline audit
omcp helm upgrade obs -- -n monitoring --set sources.prometheusUrl=http://prom:9090

插件安装／验证会复用服务端的默认拒绝签名及完整性检查（支持离线；隔离网络环境可使用 --offline-dir）。额外的 helm 标志会在字面量 -- 后传递。

文档

• 配置 — 路径、环境变量、${VAR} 替换、完整的 sources.yaml 参考
• 身份验证与 TLS — Basic、Bearer、自定义 CA、mTLS
• 管理平面身份验证（basic 模式） — 可选的登录界面 + 用于 Web UI / /api/* 平面的签名会话 Cookie
• 日志脱敏 — 在 query_logs 输出到达 Agent 之前，自动屏蔽 PII / 密钥模式；可通过 OMCP_REDACTION=off 选择关闭
• 访问控制概览 + 操作手册 — RBAC 角色、审计链、按身份设置的速率限制、服务目录增强，以及用于调查最常见“谁 / 为什么”问题的操作手册
• Prometheus — 默认值、标签解析、resolvedSeries、prom-client 兼容性
• Loki — 标签回退、Docker 容器斜杠、托管 Loki
• 连接器 — 编写自己的后端
• Agent — Ollama 设置、循环行为
• 故障排查 — 常见问题与解决方法
• 安全 — 自动化流水线、漏洞报告、内置保护
• 隔离网络部署 — 镜像镜像、私有插件、适合 GitOps 的配置
• 拓扑词汇表 — 每个支持拓扑的连接器都会输出的规范 kind / relation 约定，以及仅发出警告的验证器
• RCA 基准测试 — 可复现的 A/B 测试框架；对于跨命名空间影响范围问题（llama3.1:8b，n=10），基线工具集得分为 0/10，并会幻觉出错误的实体类型；同一模型搭配拓扑工具则可确定性地达到 10/10——完整情况请参阅三个场景的表格
• 与相近工具的比较 — 对比 Datadog Bits AI、HolmesGPT、Robusta 的注明来源表格，说明各自最擅长的领域以及本项目的定位
• 治理访问控制门控 — 通过签名授权令牌启用可选的 RBAC / 目录 / 审计（默认关闭）
• 连接器中心 — 浏览有版本管理且经过签名的连接器（目录：hub/）
• 使用场景 — 五种场景及驱动它们的提示词

端点

服务	URL
MCP 服务（Streamable HTTP）	http://localhost:3000/mcp
Web UI	http://localhost:3000
健康 API	http://localhost:3000/api/health

在 docker-compose 演示中：Prometheus 位于 :9090，Loki 位于 :3100。三个示例服务以 Kubernetes Deployment 的形式运行在 compose 内的 k3s 中，并可通过 NodePort 映射 :8080–:8082 从主机访问——URL 与 k8s 迁移前相同，因此现有 chaos 命令仍可正常使用。

传输方式： 默认使用 Streamable HTTP（/mcp）。对于基于 stdio 的客户端 / 目录（Claude Desktop、Glama 的 mcp-proxy 等），请使用 --stdio（或 MCP_TRANSPORT=stdio）运行——通过 stdin/stdout 运行一个 MCP 服务，所有日志写入 stderr，以确保协议流保持干净。

技术栈

TypeScript + Node 22.15+、@modelcontextprotocol/sdk（Streamable HTTP）、Express、Zod、js-yaml、prom-client（示例服务）、Prometheus、Loki、Promtail、Docker Compose、可选的 Ollama。

要求

• 独立运行： Node 22.15+（或仅需 npx）
• Docker 演示： Docker + Compose，4 GB+ RAM（使用 Ollama 时需 8 GB+）
• 可选： 在主机上运行 Ollama，以进行 Agent 的大模型分析

贡献

1. Fork 仓库并运行 docker-compose up --build。
2. 选择一个议题，或新建议题讨论你的想法。
3. 提交 PR——所有代码都在 Docker 中运行，无需本地依赖。

想法：新增连接器（InfluxDB、Elasticsearch、Datadog）、其他分析算法、UI 改进。

许可证

Apache License 2.0 — 另请参阅 NOTICE。

截至最后一个采用 MIT 许可证的版本（含该版本）的发布版本仍采用 MIT 许可证；此后的发布版本采用 Apache-2.0 许可证。贡献者须签署贡献者许可协议。

---