How do I install Obs?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Obs need an API key?

No required environment variable is listed on this record.

When was Obs last checked?

Last checked 2026-10-28. MCP server to allow LLMs to interact with a running Prometheus, Thanos, Alertmanager and optionally Tempo, OpenTelemetry Collector and Loki instances via the API

Servidor MCP Obs

Potencia tu agente

Añadir este servidor

Install from the publisher. Not a PlugMCP endpoint.

Ejecutar en PlugMCP

Host a copy with our keys and logs.

No packaged release in the registry yet. Follow the repository README.

RepositoryPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Ejecutar en PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Abrir

Server facts

Local

Transport: stdio
License: Apache-2.0
Last checked: 2026-10-28

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

obs mcp server

obs-mcp is an MCP server that lets LLMs query Prometheus or Thanos Querier and Alertmanager in Kubernetes. It optionally supports Loki for logs, Grafana Tempo for traces, and OpenTelemetry Collector configuration assistance. Enable additional toolsets with --toolsets (e.g., --toolsets observability/metrics,observability/logs,observability/traces,observability/otelcol).

[!NOTE] This project is moved from jhadvig/genie-plugin preserving the history of commits.

Quickstart

Run make help to see all available commands.

1. Using Kubeconfig (OpenShift)

The easiest way to get the obs-mcp connected to the cluster is via a kubeconfig:

Login into your OpenShift cluster
Run the server with

make run

Or directly:

go run ./cmd/obs-mcp/ --listen 127.0.0.1:9100 --auth-mode kubeconfig --insecure

This will auto-discover the metrics backend in OpenShift. By default, it tries thanos-querier route first, then falls back to prometheus-k8s route. Use --metrics-backend to control which route is preferred.

[!WARNING] kubeconfig auth mode requires a bearer token. Run oc whoami -t to verify you have one.

If it fails, either:

Re-login with: oc login --token=<token> or oc login -u user -p password

Use port-forwarding with --auth-mode header instead

Example using Prometheus as the preferred backend:

go run ./cmd/obs-mcp/ --listen 127.0.0.1:9100 --auth-mode kubeconfig --metrics-backend prometheus --insecure

Example using Thanos as the preferred backend:

[!NOTE]

Thanos versions before v0.40.0 do not expose the /api/v1/status/tsdb endpoint, so guardrails that rely on TSDB stats (max-metric-cardinality, disallow-blanket-regex with max-label-cardinality > 0) will fail. Use --guardrails=none or --guardrails='!tsdb' when using older Thanos versions. Thanos v0.40.0+ (#8484) added TSDB status support to the Query component, so guardrails should work if your cluster runs that version or later.

make run-no-guardrails

Or directly:

go run ./cmd/obs-mcp/ --listen 127.0.0.1:9100 --auth-mode kubeconfig --metrics-backend thanos --insecure --guardrails=none

[!IMPORTANT] How the Metrics Backend URL is Determined:

PROMETHEUS_URL environment variable (if set, always used)

--metrics-backend flag route discovery (only in kubeconfig mode)

Default: http://localhost:9090

Example using explicit PROMETHEUS_URL:

PROMETHEUS_URL=https://thanos-querier.openshift-monitoring.svc:9091/ make run

[!IMPORTANT] How the Loki URL is determined (when observability/logs toolset is enabled):

--loki-url flag

LOKI_URL environment variable

lokiNamespace/lokiName tool parameters for each MCP tool call (except loki_list_instances)

[!IMPORTANT] How the Tempo URL is determined (when observability/traces toolset is enabled):

--traces.tempo-url flag

TEMPO_URL environment variable

tempoNamespace/tempoName tool parameters for each MCP tool call (except tempo_list_instances)

2. Port-forwarding alternative

Port-forwards prometheus-k8s-0:9090 to localhost and starts obs-mcp with header auth. Requires oc login:

make run-openshift-pf-prometheus

3. Local Development with Kind (using E2E test infrastructure)

Use the E2E test infrastructure for a fully working local environment with Prometheus:

Setup Kind cluster with Prometheus

make test-e2e-setup

This creates a Kind cluster with:

Prometheus Operator, Prometheus, and Alertmanager
Tempo Operator and a sample tracing application
Loki Operator and a test LokiStack

Build and deploy obs-mcp

make test-e2e-deploy

Port forward obs-mcp

kubectl port-forward -n obs-mcp svc/obs-mcp 9100:9100

To connect an MCP client, use http://localhost:9100/mcp.

When done:

make test-e2e-teardown

See TESTING.md for more details.

4. Using prometheus helm chart in local Kubernetes cluster

# add the prometheus-community Helm repo (once)
helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
helm repo update

# install Prometheus (and exporters) on your local cluster
helm install local prometheus-community/prometheus

# port-forward Prometheus server
export POD_NAME=$(kubectl get pods --namespace default -l "app.kubernetes.io/name=prometheus,app.kubernetes.io/instance=local" -o jsonpath="{.items[0].metadata.name}") && kubectl --namespace default port-forward $POD_NAME 9090

go run ./cmd/obs-mcp/ --auth-mode header --insecure --listen :9100

Testing with curl

You can test the MCP server using curl. The server uses JSON-RPC 2.0 over HTTP.

[!TIP] For formatted JSON output, pipe the response to jq:

curl ... | jq

List available tools:

[!NOTE] The default --toolsets value is observability/metrics only. Additional toolsets:

observability/logs - Loki log query tools (requires Loki URL or LokiStack discovery)

observability/traces - Tempo tracing tools (requires Tempo configuration)

observability/otelcol - OpenTelemetry Collector configuration assistance (no external dependencies)

Example: --toolsets observability/metrics,observability/logs,observability/traces,observability/otelcol

curl -X POST http://localhost:9100/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'|jq

Call the list_metrics tool:

curl -X POST http://localhost:9100/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_metrics","arguments":{}}}' | jq

Execute a range query (e.g., get up metrics for the last hour):

curl -X POST http://localhost:9100/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"execute_range_query","arguments":{"query":"up{job=\"prometheus\"}","step":"1m","end":"NOW","duration":"1h"}}}' | jq

Testing with MCP Inspector

Use the MCP Inspector to visually test and debug obs-mcp tools.

Using container compose

Kind

Set up a Kind cluster with Prometheus and Alertmanager (if not already running):
```
make test-e2e-setup
```

Port-forward Prometheus and Alertmanager from your Kind cluster:

kubectl port-forward -n monitoring pod/prometheus-k8s-0 9090:9090 &

kubectl port-forward -n monitoring pod/alertmanager-main-0 9093:9093 &

OpenShift

Port-forward Prometheus and Alertmanager from your OpenShift cluster:

oc port-forward -n openshift-monitoring pod/prometheus-k8s-0 9090:9090 &

oc port-forward -n openshift-monitoring pod/alertmanager-main-0 9093:9093 &

Start obs-mcp and the Inspector (builds the obs-mcp container and starts both services via compose):
```
make inspect
```
This uses Docker by default. For podman, use:
```
CONTAINER_CLI=podman make inspect
```
Open the Inspector URL from the logs (includes the auth token):
```
http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=<token>
```
Connect using Streamable HTTP transport to http://obs-mcp:8080/mcp

Development and code ownership

obs-mcp is a thin standalone host for the observability packages in kubernetes-mcp-server. Tool definitions/handlers live in upstream pkg/toolsets/{metrics,logs,traces,otelcol}; backend clients, discovery, authentication, and instrumentation live in upstream pkg/obs/.
This repository retains the CLI (cmd/obs-mcp), Go MCP SDK adapter (pkg/mcp), health server, kubeconfig helpers, and standalone cluster-inspector stub. Only explicitly selected observability toolsets are exposed; standalone registration does not apply target-compatibility filtering.
Change shared tool behavior and its unit tests upstream. Run make generate-tools-doc here to regenerate TOOLS.md from the pinned upstream definitions; standalone integration and cluster e2e tests stay here.

Documentation

Document	Description
DEPLOYMENT.md	Authentication modes, in-cluster deployment, configuration
TOOLS.md	Available MCP tools
TESTING.md	Testing guide
RELEASE.md	Release process and versioning guidelines
CHANGELOG.md	Notable changes per release
MCPChecker Evals	Automated eval framework for tool verification
KUBE_MCP_SYNC.md	`/kube-mcp-sync` skill for kubernetes-mcp-server compatibility

License

Apache 2.0

Añadir este servidor

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install Obs?

Does Obs need an API key?

What transport does Obs use?

When was Obs last checked?

Documentation

obs mcp server

Quickstart

1. Using Kubeconfig (OpenShift)

2. Port-forwarding alternative

3. Local Development with Kind (using E2E test infrastructure)

Setup Kind cluster with Prometheus

Build and deploy obs-mcp

Port forward obs-mcp

4. Using prometheus helm chart in local Kubernetes cluster

Testing with curl

Testing with MCP Inspector

Using container compose

Kind

OpenShift

Development and code ownership

Documentation

License