# Obs Mcp

> MCP server to allow LLMs to interact with a running Prometheus, Thanos, Alertmanager, Tempo and Loki instances via the API

- **Type:** MCP server
- **Install:** `agentstack add mcp-rhobs-obs-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [rhobs](https://agentstack.voostack.com/s/rhobs)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [rhobs](https://github.com/rhobs)
- **Source:** https://github.com/rhobs/obs-mcp

## Install

```sh
agentstack add mcp-rhobs-obs-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# obs mcp server

[](https://github.com/rhobs/obs-mcp/actions/workflows/lint.yaml)
[](https://github.com/rhobs/obs-mcp/actions/workflows/unit.yaml)
[](https://github.com/rhobs/obs-mcp/actions/workflows/e2e.yaml)
[](https://github.com/rhobs/obs-mcp/actions/workflows/docs.yaml)

obs-mcp is an [MCP](https://modelcontextprotocol.io/introduction) server that lets LLMs query [Prometheus](https://prometheus.io/) or [Thanos Querier](https://thanos.io/) and [Alertmanager](https://prometheus.io/docs/alerting/latest/alertmanager/) in Kubernetes. It optionally supports [Loki](https://grafana.com/oss/loki/) for logs, [Grafana Tempo](https://grafana.com/docs/tempo/latest/) for traces, and [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/) configuration assistance. Enable additional toolsets with `--toolsets` (e.g., `--toolsets metrics,logs,traces,otelcol`).

> [!NOTE]
> This project is moved from [jhadvig/genie-plugin](https://github.com/jhadvig/genie-plugin/tree/main/obs-mcp) 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:

 1. Login into your OpenShift cluster
 2. Run the server with

 ```shell
 make run
 ```

 Or directly:

 ```shell
 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=` or `oc login -u user -p password`
> - Use [port-forwarding](#2-port-forwarding-alternative) with `--auth-mode header` instead

**Example using Prometheus as the preferred backend:**

```shell
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](https://github.com/thanos-io/thanos/pull/8484)) added TSDB status support to the Query component, so guardrails should work if your cluster runs that version or later.

```shell
make run-no-guardrails
```

Or directly:

```shell
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:**
>
> 1. `PROMETHEUS_URL` environment variable (if set, always used)
> 2. `--metrics-backend` flag route discovery (only in `kubeconfig` mode)
> 3. Default: `http://localhost:9090`
>
>
> **Example using explicit PROMETHEUS_URL:**
>
  ```shell
  PROMETHEUS_URL=https://thanos-querier.openshift-monitoring.svc:9091/ make run
  ```

> [!IMPORTANT]
> **How the Loki URL is Determined (when `logs` toolset is enabled):**
>
> 1. `--loki-url` flag (if set)
> 2. `LOKI_URL` environment variable
> 3. Default: `http://localhost:3100` (kubeconfig mode only)
>
> In `header` and `serviceaccount` modes, you can either set `--loki-url`/`LOKI_URL` **or** use LokiStack discovery (`loki_list_instances` + `lokiNamespace`/`lokiName` arguments).

### 2. Port-forwarding alternative

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

```shell
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

```bash
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

```bash
make test-e2e-deploy
```

#### Port forward obs-mcp

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

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

When done:

```bash
make test-e2e-teardown
```

See [TESTING.md](TESTING.md) for more details.

### 4. Using prometheus helm chart in local Kubernetes cluster

```shell
# 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 `metrics` only. Additional toolsets:
>
> - `logs` - Loki log query tools (requires Loki URL or LokiStack discovery)
> - `traces` - Tempo tracing tools (requires Tempo configuration)
> - `otelcol` - OpenTelemetry Collector configuration assistance (no external dependencies)
>
> Example: `--toolsets metrics,logs,traces,otelcol`

```shell
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:**

```shell
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):**

```shell
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](https://github.com/modelcontextprotocol/inspector) to visually test and debug obs-mcp tools.

#### Using container compose

##### Kind

1. Set up a Kind cluster with Prometheus and Alertmanager (if not already running):

   ```bash
   make test-e2e-setup
   ```

2. Port-forward Prometheus and Alertmanager from your Kind cluster:

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

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

##### OpenShift

1. Port-forward Prometheus and Alertmanager from your OpenShift cluster:

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

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

2. Start obs-mcp and the Inspector (builds the obs-mcp container and starts both services via compose):

   ```bash
   make inspect
   ```

   This uses Docker by default. For podman, use:

   ```bash
   CONTAINER_CLI=podman make inspect
   ```

3. Open the Inspector URL from the logs (includes the auth token):

   ```text
   http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=
   ```

4. Connect using **Streamable HTTP** transport to `http://obs-mcp:8080/mcp`

## Documentation

| Document | Description |
|----------|-------------|
| [DEPLOYMENT.md](docs/DEPLOYMENT.md) | Authentication modes, in-cluster deployment, configuration |
| [TOOLS.md](TOOLS.md) | Available MCP tools |
| [TESTING.md](TESTING.md) | Testing guide |
| [RELEASE.md](RELEASE.md) | Release process and versioning guidelines |
| [CHANGELOG.md](CHANGELOG.md) | Notable changes per release |
| [MCPChecker Evals](evals/mcpchecker/README.md) | Automated eval framework for tool verification |

## License

[Apache 2.0](LICENSE)

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [rhobs](https://github.com/rhobs)
- **Source:** [rhobs/obs-mcp](https://github.com/rhobs/obs-mcp)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-rhobs-obs-mcp
- Seller: https://agentstack.voostack.com/s/rhobs
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.