observability-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@observability-mcp show error logs from the last hour"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
observability-mcp
MCP (Model Context Protocol) servers that let AI assistants query your observability stack — Grafana/Loki for logs and Thanos/Prometheus for metrics — directly from Cursor, Claude Desktop, or any MCP-compatible client.
Packages
Package | Entry-point | What it does |
|
| Query Loki logs via Grafana datasource proxy |
|
| Query Prometheus/Thanos metrics (PromQL) |
|
| Combined server — all tools in one connection |
Related MCP server: mcp-server-logs-sieve
Requirements
Python 3.10+
Access to a running Grafana instance (for
grafana_mcp)Access to a Thanos or Prometheus instance (for
thanos_mcp)
Installation
From GitHub (recommended)
Install directly from the repo without cloning:
pip install "observability-mcp @ git+https://github.com/ThainaJardim/observability-mcp.git"
# With browser-cookie support for Grafana SSO:
pip install "observability-mcp[browser-cookie] @ git+https://github.com/ThainaJardim/observability-mcp.git"After installation, the grafana-mcp, thanos-mcp, and observability-mcp commands are available.
From source (local clone)
git clone https://github.com/ThainaJardim/observability-mcp.git
cd observability-mcp
pip install .
# For automatic Grafana SSO login via browser cookies (macOS/Linux):
pip install ".[browser-cookie]"Quick start
Grafana / Loki
export GRAFANA_URL=https://grafana.example.com
export LOKI_DATASOURCE_ID=1 # numeric datasource ID in Grafana
export OIDC_ISSUER=https://keycloak.example.com/auth/realms/myrealm
grafana-mcpThanos / Prometheus
export THANOS_URL=https://thanos.example.com
export OIDC_ISSUER=https://keycloak.example.com/auth/realms/myrealm
thanos-mcpCombined (both in one server)
# Set all env vars from above, then:
observability-mcpAuthentication
Grafana MCP
Auth mode is auto-detected from environment variables (or forced with
GRAFANA_AUTH_MODE):
Mode | How it works | Variables needed |
| Reads Keycloak SSO cookies from Chrome, follows the Grafana OAuth flow automatically, caches |
|
| Grafana service-account token |
|
| Static |
|
| OIDC id-token from kubectl kubeconfig |
|
browser-cookie mode requires
browser-cookie3(pip install ".[browser-cookie]"). On first use it reads Chrome's cookie store — you may be prompted to allow macOS Keychain access. You must be logged into Grafana in Chrome at least once.
Thanos MCP
Auth mode is auto-detected (or forced with THANOS_AUTH_MODE):
Mode | How it works | Variables needed |
| OIDC id-token from kubectl kubeconfig, auto-refreshed |
|
| Static Bearer token |
|
| oauth2-proxy session cookie |
|
Cursor MCP configuration
Create or edit .cursor/mcp.json in your project:
{
"mcpServers": {
"grafana": {
"command": "python",
"args": ["-m", "grafana_mcp.server"],
"env": {
"GRAFANA_URL": "https://grafana.example.com",
"LOKI_DATASOURCE_ID": "1",
"OIDC_ISSUER": "https://keycloak.example.com/auth/realms/myrealm",
"PATH": "/usr/local/bin:/usr/bin:/bin"
}
},
"thanos": {
"command": "python",
"args": ["-m", "thanos_mcp.server"],
"env": {
"THANOS_URL": "https://thanos.example.com",
"OIDC_ISSUER": "https://keycloak.example.com/auth/realms/myrealm",
"PATH": "/usr/local/bin:/usr/bin:/bin"
}
}
}
}Tip: Use an absolute Python interpreter path (e.g.
/usr/local/bin/python3) if Cursor cannot findpythonin its PATH.
Combined server (one entry)
{
"mcpServers": {
"observability": {
"command": "python",
"args": ["-m", "observability_mcp.server"],
"env": {
"GRAFANA_URL": "https://grafana.example.com",
"LOKI_DATASOURCE_ID": "1",
"THANOS_URL": "https://thanos.example.com",
"OIDC_ISSUER": "https://keycloak.example.com/auth/realms/myrealm",
"PATH": "/usr/local/bin:/usr/bin:/bin"
}
}
}
}Available MCP tools
Grafana/Loki tools (grafana_mcp)
Tool | Description |
| Run a LogQL range query and return matching log streams |
| Run a LogQL instant query |
| List all available Loki label names |
| List values for a specific Loki label |
Thanos/Prometheus tools (thanos_mcp)
Tool | Description |
| Run an instant PromQL query |
| Run a PromQL range query |
| List all metric label names |
| List time-series matching a selector |
Development
# Install in editable mode with dev extras
pip install -e ".[dev,browser-cookie]"
# Run tests
pytest
# Run a specific server locally
python -m grafana_mcp.server
python -m thanos_mcp.server
python -m observability_mcp.serverEnvironment variable reference
Variable | Default | Description |
| (required) | Grafana base URL |
| (required) | Numeric Loki datasource ID in Grafana |
| auto | Force Grafana auth mode |
| — | Grafana service-account token |
| — | grafana_session cookie value |
|
| Path to session cache file |
| (required) | Thanos/Prometheus base URL |
| auto | Force Thanos auth mode |
| — | Static Bearer token |
| — | oauth2-proxy cookie value |
| — | OIDC issuer URL (Keycloak realm URL) |
|
| HTTP timeout for all requests |
|
| Logging level |
License
MIT
Available Tools
8 toolslist_labelsA
List all metric label names available in Thanos.
Args: start: Optional start of the time range for label filtering. end: Optional end of the time range for label filtering.
Returns: JSON array of label name strings.
Inputs: end, start. Returns: object
list_loki_labelsA
List available Loki label names from the configured datasource.
Args: start: Optional start of the time range for filtering. end: Optional end of the time range for filtering.
Returns: JSON array of label name strings.
Inputs: end, start. Returns: object
list_loki_label_valuesA
List available values for a given Loki label.
Args:
label: Label name, e.g. "app" or "namespace".
start: Optional start of the time range for filtering.
end: Optional end of the time range for filtering.
Returns: JSON array of label value strings.
Inputs: label (required), end, start. Returns: object
list_seriesA
List time-series matching a PromQL selector.
Args:
match: One or more comma-separated series selectors, e.g.
{job="prometheus"} or up,{job="api"}.
Each comma-separated value is sent as a separate match[]
parameter.
start: Optional start timestamp for the look-up window.
end: Optional end timestamp for the look-up window.
Returns: JSON array of label-set objects describing each matching series.
Inputs: match (required), end, start. Returns: object
query_loki_instantA
Run a Loki instant query through Grafana datasource proxy.
Args: query: LogQL expression. limit: Maximum number of log lines to return (1–5000, default 100). at: Evaluation timestamp. RFC 3339 or Unix nanosecond string. Defaults to now when omitted.
Returns: JSON payload from Loki with matching log entries.
Inputs: query (required), at, limit. Returns: object
query_loki_logsA
Run a Loki range query through Grafana datasource proxy.
Args:
query: LogQL expression, e.g. {app="myservice"} |= "error".
limit: Maximum number of log lines to return (1–5000, default 100).
direction: "backward" (newest first, default) or "forward".
start: Start of the time range. RFC 3339 or Unix nanosecond string.
end: End of the time range. RFC 3339 or Unix nanosecond string.
Returns: JSON payload from Loki with streams and log entries.
Inputs: query (required), end, limit, start, +1 more. Returns: object
query_metricsA
Run an instant PromQL query against Thanos.
Args:
query: PromQL expression, e.g. rate(http_requests_total[5m]).
time: Optional evaluation timestamp. Accepts RFC 3339 strings
(2024-01-01T00:00:00Z) or Unix timestamps as strings.
Defaults to now when omitted.
Returns:
JSON payload from Thanos containing resultType and result.
Inputs: query (required), time. Returns: object
query_metrics_rangeA
Run a PromQL range query against Thanos.
Args:
query: PromQL expression.
start: Start of the time range. RFC 3339 or Unix timestamp string.
end: End of the time range. RFC 3339 or Unix timestamp string.
step: Query resolution step width. Duration string (60s, 5m)
or float seconds.
Returns:
JSON payload with resultType: "matrix" and the time-series data.
Inputs: end (required), step (required), query (required), start (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool targets a distinct operation and data source (Loki vs. Thanos), with clear naming and descriptions that prevent confusion. Even similar tasks like label listing are differentiated by the datasource prefix.
All tools follow a consistent verb_noun pattern in snake_case, e.g., 'query_loki_instant', 'list_labels'. The naming clearly indicates the action and the target, making it predictable and easy to understand.
With 8 tools covering essential operations for two datasources (metrics and logs), the count is well-scoped. There are no redundant tools, and each tool serves a clear purpose without overwhelming the agent.
The tool set covers the core query and metadata exploration for both Loki and Thanos, including instant/range queries, label discovery, and series listing. No obvious gaps exist for standard observability workflows.
Maintenance
Related MCP Connectors
Query application logs, traces, and metrics from your AI coding assistant via Foam's MCP server.
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
Talk to your public-facing AI from any MCP client — Claude, ChatGPT, Cursor, Cline, Windsurf.
MCP server for Sentry - error monitoring, issue tracking, and debugging for AI assistants
Related MCP Servers
- AlicenseAqualityDmaintenanceA server that enables AI assistants to access and query Grafana dashboards, metrics, logs, and configurations through an MCP protocol interface.106MIT
- AlicenseNot gradedqualityBmaintenanceAn MCP server that connects Claude (or any MCP compatible client) to your existing log infrastructure. Query, summarize, and trace logs in plain English across GCP Cloud Logging, AWS CloudWatch, Azure Log Analytics, Grafana Loki, and Elasticsearch without writing filter expressions or leaving your editor.5MIT
- FlicenseNot gradedqualityDmaintenanceAn MCP server that enables AI assistants to query and analyze logs from Grafana Loki using LogQL, supporting label discovery and keyword search.4-
- AlicenseNot gradedqualityCmaintenanceAn MCP server that enables AI assistants to query and explore your OpenObserve observability data. Provides read-only access to logs, metrics, and traces for analysis and troubleshooting.5MIT