Grafana MCP Agent

A Model Context Protocol (MCP) service layer tailored for the Grafana observability platform.

This component grants external systems access to manage and interrogate your Grafana deployment and its integrated monitoring backend.

Prerequisites

Functionality relies heavily on Grafana version 9.0 or newer. Older releases may lack necessary API endpoints, causing failures, especially for data source configuration interactions.

Capabilities Overview

This section details the current operational scope of the MCP service. It is purely informational and does not constitute a commitment to future feature parity or roadmap direction.

Visualization Configuration (Dashboards)

• Discovery: Locate dashboards based on naming conventions or associated metadata.
• Retrieval by UID: Fetch the complete configuration payload for a dashboard using its unique identifier. Caution: Large payloads risk exceeding context window limits.
• Summary Retrieval: Obtain a concise summary, including panel counts, panel technology types, variable definitions, and essential metadata, optimized to minimize context overhead.
• Targeted Extraction: Utilize JSONPath syntax to selectively pull specific dashboard segments (e.g., $.title, $.panels[*].targets) to conserve context space.
• Modification/Creation: Permitting full overwrite or the establishment of new dashboard definitions. Warning: Inputting the entire JSON structure consumes substantial context.
• Partial Updates (Patching): Apply granular modifications to a dashboard definition without transmitting the whole file, drastically cutting context usage for targeted edits.
• Panel Detail Inspection: Extract query text, panel titles, and associated data source metadata (UID/type) for every visualization pane.

Context Management Protocols

Specific methods are integrated to mitigate context exhaustion (see issue #101):

• Employ get_dashboard_summary for high-level assessment and modification planning.
• Leverage get_dashboard_property with precise JSONPath for data subset retrieval.
• Reserve get_dashboard_by_uid exclusively for scenarios where the complete JSON structure is mandatory.

Data Source Registry

• Inventory and Detail Fetch: Enumerate all registered data sources and retrieve their comprehensive configuration details.
• Currently supports direct interaction with Prometheus and Loki types.

Time Series Data Acquisition (Prometheus)

• PromQL Execution: Run both instantaneous and time-series PromQL expressions against configured Prometheus instances.
• Metadata Exploration: Retrieve available metric names, associated label keys, and their respective values from Prometheus.

Log & Metric Stream Acquisition (Loki)

• LogQL Operations: Execute both log stream queries and metric aggregations using LogQL against Loki data sources.
• Index Metadata: Examine available log label keys, their values, and stream statistical summaries within Loki.

Incident Management (Grafana Incident)

• Lifecycle Operations: Capabilities to search existing incidents, provision new ones, and append activity records within the Incident framework.

Observability Tracing Analysis (Sift)

• Investigation Listing: Retrieve a paginated manifest of Sift investigations.
• Investigation Deep Dive: Fetch specific details for an investigation identified by its UUID.
• Analysis Retrieval: Access discrete analysis reports associated with a Sift investigation.
• Error Pattern Detection: Analyze Loki logs to isolate elevated error signatures via Sift processing.
• Latency Identification: Pinpoint protracted request spans using Sift's integration with Tempo.

Alerting Framework Management

• Rule Inventory: List all configured alert definitions and their current evaluation states (e.g., Firing, Normal, Error).
• Notification Endpoints: View the defined set of contact points used for rule notifications.

On-Call Coordination (Grafana OnCall)

• Schedule Oversight: View and modify on-call duty rosters.
• Shift Specifics: Retrieve granular details pertaining to individual scheduling blocks.
• Current Assignment Check: Determine which users are presently responsible for a given schedule.
• Team/User Directory: Enumerate all associated OnCall teams and personnel.
• Alert Group Monitoring: Query and filter aggregated alert groups based on status, integration source, labels, or temporal windows.
• Group Detail Fetch: Obtain specific data points for an alert group identified by its internal ID.

Administrative Utilities

• Team Roster: List all established user groups within the organization.
• User Directory: Retrieve a list of all users belonging to the active organization.

Contextual Navigation

• URL Generation: Produce exact, actionable deep links for Grafana resources, removing reliance on potentially inaccurate LLM guesswork for URL construction.
  • Dashboard Links: Direct links to specific dashboards using their UID (e.g., http://localhost:3000/d/dashboard-uid).
  • Panel Focus Links: Links targeting specific visualization components via the viewPanel parameter (e.g., http://localhost:3000/d/dashboard-uid?viewPanel=5).
  • Explore Initialization: Generate Explore URLs pre-populated with data sources (e.g., http://localhost:3000/explore?left={"datasource":"prometheus-uid"}).
  • Temporal Scoping: Incorporate time range parameters (from=now-1h&to=now) into generated URLs.
  • Parameter Injection: Support for appending arbitrary query parameters, such as dashboard variables or refresh settings.

The toolset's availability is dynamic. You control which functionalities are exposed to the MCP client, which is useful for optimizing context consumption or excluding unused features. Disabling entire functional groups is achieved via command-line flags upon server startup (e.g., --disable-oncall to deactivate OnCall capabilities, or --disable-navigation for link generation).

Role-Based Access Control (RBAC) Requirements

Each tool mandates specific RBAC permissions for successful operation. When provisioning the service account for the MCP agent, confirm it possesses the minimum necessary privileges corresponding to the activated tools. Required scopes (e.g., datasources:*, dashboards:*, folders:*) may also be necessary depending on the access granularity intended.

Note: Grafana Incident and Sift tools adhere to conventional Grafana roles rather than granular RBAC: - Viewer Role: Necessary for read-only actions (listing incidents, retrieving investigation data). - Editor Role: Necessary for mutable actions (creating incidents, modifying investigations).

Consult the official Grafana documentation for exhaustive RBAC details.

RBAC Scope Definitions

Scopes delineate the boundaries of permission application. Valid actions require the convergence of both the correct permission level and its associated scope.

General Scope Patterns:

• Wide Authorization: Utilize the * wildcard for organization-wide resource access:

  • datasources:* - Full access to all data sources.
  • dashboards:* - Full access to all dashboards.
  • folders:* - Full access to all dashboard folders.
  • teams:* - Full access to all teams.

• Restricted Authorization: Employ specific UIDs or IDs to limit access to individual entities:

  • datasources:uid:prometheus-uid - Permits interaction solely with the specified Prometheus data source.
  • dashboards:uid:abc123 - Restricted to the dashboard identified by UID abc123.
  • folders:uid:xyz789 - Limited to folder UID xyz789.
  • teams:id:5 - Limited to team with internal ID 5.
  • global.users:id:123 - Limited to user ID 123.

Authorization Examples:

• Maximum MCP Operation: Grant extensive permissions across all integrated features.

datasources: (datasources:read, datasources:query) dashboards: (dashboards:read, dashboards:create, dashboards:write) folders: (required for dashboard creation and alert rule context) teams: (teams:read) global.users:* (users:read)

• Constrained Data Source Querying: Limit access strictly to operational data sources.

datasources:uid:prometheus-prod (datasources:query) datasources:uid:loki-prod (datasources:query)

• Read-Only Dashboard Access: Restrict dashboard interactions to specific views.

dashboards:uid:monitoring-dashboard (dashboards:read) dashboards:uid:alerts-dashboard (dashboards:read)

Tool Registry

Tool	Category	Functionality Summary	Mandated RBAC Permissions	Required Scopes
list_teams	Admin	Retrieve organizational teams roster.	teams:read	teams:* or specific ID
list_users_by_org	Admin	Fetch all users within the current organization.	users:read	global.users:* or specific ID
search_dashboards	Search	Execute searches across the dashboard catalog.	dashboards:read	dashboards:* or specific UID
get_dashboard_by_uid	Dashboard	Fetch full dashboard definition by its UID.	dashboards:read	dashboards:uid:abc123
update_dashboard	Dashboard	Create or modify a dashboard entity.	dashboards:create, dashboards:write	dashboards:*, folders:* or specific folder UID
get_dashboard_panel_queries	Dashboard	Extract panel content (queries, data source refs).	dashboards:read	dashboards:uid:abc123
get_dashboard_property	Dashboard	Extract granular dashboard attributes using JSONPath.	dashboards:read	dashboards:uid:abc123
get_dashboard_summary	Dashboard	Get a resource-efficient, high-level dashboard snapshot.	dashboards:read	dashboards:uid:abc123
list_datasources	Datasources	Inventory all configured data source connections.	datasources:read	datasources:*
get_datasource_by_uid	Datasources	Retrieve configuration details for a data source by its UID.	datasources:read	datasources:uid:prometheus-uid
get_datasource_by_name	Datasources	Retrieve configuration details for a data source by its name.	datasources:read	datasources:* or specific Loki UID
query_prometheus	Prometheus	Execute PromQL commands against configured Prometheus instances.	datasources:query	datasources:uid:prometheus-uid
list_prometheus_metric_metadata	Prometheus	Fetch metadata associated with metrics.	datasources:query	datasources:uid:prometheus-uid
list_prometheus_metric_names	Prometheus	List all discoverable metric identifiers.	datasources:query	datasources:uid:prometheus-uid
list_prometheus_label_names	Prometheus	List label keys conforming to a selector.	datasources:query	datasources:uid:prometheus-uid
list_prometheus_label_values	Prometheus	List permissible values for a specified Prometheus label key.	datasources:query	datasources:uid:prometheus-uid
list_incidents	Incident	Query the current registry of incidents in Grafana Incident.	Viewer role	N/A
create_incident	Incident	Provision a new incident record.	Editor role	N/A
add_activity_to_incident	Incident	Log a new event entry against an active incident.	Editor role	N/A
get_incident	Incident	Retrieve the complete record for a specified incident ID.	Viewer role	N/A
query_loki_logs	Loki	Execute LogQL to fetch structured logs or derived metrics.	datasources:query	datasources:uid:loki-uid
list_loki_label_names	Loki	Enumerate all label keys present in the Loki index.	datasources:query	datasources:uid:loki-uid
list_loki_label_values	Loki	Retrieve permissible values for a given Loki label key.	datasources:query	datasources:uid:loki-uid
query_loki_stats	Loki	Obtain internal statistical summaries of log streams.	datasources:query	datasources:uid:loki-uid
list_alert_rules	Alerting	View all alert definitions and their status outcomes.	alert.rules:read	folders:* or specific folder UID
get_alert_rule_by_uid	Alerting	Fetch a specific alert rule using its unique identifier.	alert.rules:read	folders:uid:alerts-folder
list_contact_points	Alerting	List all configured notification receivers.	alert.notifications:read	Global scope
list_oncall_schedules	OnCall	Retrieve the catalog of active OnCall schedules.	grafana-oncall-app.schedules:read	Plugin-specific scopes
get_oncall_shift	OnCall	Fetch detailed scheduling information for a time block.	grafana-oncall-app.schedules:read	Plugin-specific scopes
get_current_oncall_users	OnCall	Identify personnel currently covered by a schedule.	grafana-oncall-app.schedules:read	Plugin-specific scopes
list_oncall_teams	OnCall	Get the roster of configured OnCall teams.	grafana-oncall-app.user-settings:read	Plugin-specific scopes
list_oncall_users	OnCall	Get the roster of OnCall users.	grafana-oncall-app.user-settings:read	Plugin-specific scopes
list_alert_groups	OnCall	Fetch aggregated alert notification groups with filtering applied.	grafana-oncall-app.alert-groups:read	Plugin-specific scopes
get_alert_group	OnCall	Retrieve full details for an alert group instance by ID.	grafana-oncall-app.alert-groups:read	Plugin-specific scopes
get_sift_investigation	Sift	Retrieve an existing Sift investigation by its UUID.	Viewer role	N/A
get_sift_analysis	Sift	Retrieve a specific analysis artifact from a Sift investigation.	Viewer role	N/A
list_sift_investigations	Sift	Retrieve a catalog of Sift investigations, supporting result limiting.	Viewer role	N/A
find_error_pattern_logs	Sift	Utilizes Sift to identify anomalous error frequency within Loki streams.	Editor role	N/A
find_slow_requests	Sift	Leverages Sift (via Tempo integration) to detect performance bottlenecks.	Editor role	N/A
list_pyroscope_label_names	Pyroscope	List label keys available for filtering profiles.	datasources:query	datasources:uid:pyroscope-uid
list_pyroscope_label_values	Pyroscope	List values associated with a specific profile label key.	datasources:query	datasources:uid:pyroscope-uid
list_pyroscope_profile_types	Pyroscope	List available profile types (e.g., cpu, heap).	datasources:query	datasources:uid:pyroscope-uid
fetch_pyroscope_profile	Pyroscope	Download a specific execution profile, typically in DOT format for visualization.	datasources:query	datasources:uid:pyroscope-uid
get_assertions	Asserts	Fetch assertion outcome summaries for a defined entity.	Plugin-specific permissions	Plugin-specific scopes
generate_deeplink	Navigation	Construct precise URL references to Grafana interface elements.	None (Read-only URL construction)	N/A

Command-Line Configuration Reference

The mcp-grafana executable accepts numerous flags for runtime customization:

Connection Mode Options: - -t, --transport: Specifies the communication protocol (stdio, sse, or streamable-http). Default is stdio. - --address: Network binding for SSE/streamable-http listeners (default: localhost:8000). - --base-path: Sets a prefix path for the SSE/streamable-http endpoint. - --endpoint-path: Defines the specific path segment for streamable-http connections (default: /).

Operation & Logging: - --debug: Activates verbose logging for all underlying HTTP interactions between the agent and Grafana.

Tool Feature Control: Flags beginning with --disable- allow granular deactivation of feature groups to conserve context or reduce required permissions.

• --enabled-tools: Overrides defaults to only activate a specific, comma-separated list of tools.
• --disable-search, --disable-datasource, --disable-incident, --disable-prometheus, --disable-loki, --disable-alerting, --disable-dashboard, --disable-oncall, --disable-asserts, --disable-sift, --disable-admin, --disable-pyroscope, --disable-navigation

Client TLS Configuration (For connections to Grafana): - --tls-cert-file: Client certificate path for mutual TLS authentication. - --tls-key-file: Client private key path corresponding to the certificate. - --tls-ca-file: Path to the Certificate Authority bundle for verifying the Grafana server certificate. - --tls-skip-verify: Bypasses all certificate validation (use sparingly).

Server TLS Configuration (For streamable-http transport to the MCP Agent): - --server.tls-cert-file: Server certificate file for HTTPS hosting. - --server.tls-key-file: Server private key file for HTTPS hosting.

Deployment and Initialization

This service is engineered to integrate seamlessly with both self-hosted Grafana stacks and Grafana Cloud instances. When using Grafana Cloud, substitute the local address (e.g., http://localhost:3000) with your cloud instance URL (e.g., https://myinstance.grafana.net).

1. Authentication Setup: Secure interaction necessitates a Grafana service account token. Create a service account in Grafana with the requisite permissions for the tools you intend to utilize, generate a token, and securely provision it for the client configuration. Refer to the Grafana service account documentation for token creation procedures.

Deprecation Notice: The environment variable GRAFANA_API_KEY is scheduled for removal. Migrate configurations to utilize GRAFANA_SERVICE_ACCOUNT_TOKEN.

1. Installation Paths: Several methods exist for deploying mcp-grafana:

2. Container Image: Utilize the official Docker Hub image.

   Critical Note: The default Docker entrypoint executes the agent in SSE mode. For standard interactions with local AI assistants (like Claude Desktop), STDIO mode is generally preferred. This requires overriding the transport flag to -t stdio and including the interactive flag -i:

   bash docker pull mcp/grafana # Execution in STDIO mode: docker run --rm -i -e GRAFANA_URL=http://localhost:3000 -e GRAFANA_SERVICE_ACCOUNT_TOKEN= mcp/grafana -t stdio # Execution in SSE mode (HTTP server on port 8000): docker run --rm -p 8000:8000 -e GRAFANA_URL=http://localhost:3000 -e GRAFANA_SERVICE_ACCOUNT_TOKEN= mcp/grafana

3. Direct Binary: Download the latest compiled artifact from the releases page and ensure the executable resides within your system's $PATH.

4. Source Compilation: If Go is installed, build and install locally:

   bash GOBIN="$HOME/go/bin" go install github.com/grafana/mcp-grafana/cmd/mcp-grafana@latest

5. Kubernetes via Helm: Deploy using the official Helm chart from the Grafana repository:

   bash helm repo add grafana https://grafana.github.io/helm-charts helm install my-release grafana/grafana-mcp --set grafana.apiKey= --set grafana.url=

6. Client Configuration: Integrate the server definition into your consuming application's configuration file (e.g., Claude Desktop's settings.json):

For Local Binary Execution (STDIO):

{ "mcpServers": { "grafana": { "command": "mcp-grafana", "args": [], "env": { "GRAFANA_URL": "http://localhost:3000", "GRAFANA_SERVICE_ACCOUNT_TOKEN": "" } } } }

For Docker Execution (STDIO Override):

{ "mcpServers": { "grafana": { "command": "docker", "args": [ "run", "--rm", "-i", "-e", "GRAFANA_URL", "-e", "GRAFANA_SERVICE_ACCOUNT_TOKEN", "mcp/grafana", "-t", "stdio" ], "env": { "GRAFANA_URL": "http://localhost:3000", "GRAFANA_SERVICE_ACCOUNT_TOKEN": "" } } } }

If you encounter Error: spawn mcp-grafana ENOENT in tools like Claude Desktop, provide the absolute path to the mcp-grafana executable.

VSCode Integration (SSE Mode): If using the default SSE mode (e.g., Docker without transport override), configure .vscode/settings.json for the endpoint:

"mcp": { "servers": { "grafana": { "type": "sse", "url": "http://localhost:8000/sse" } } }

Debug Activation

Enable comprehensive request/response logging by adding the -debug flag to the command arguments. For Docker users, ensure this flag is included in the primary arguments list for mcp/grafana.

TLS Client Configuration Details

If connecting to a secured Grafana instance, custom client certificates must be supplied using the --tls-cert-file, --tls-key-file, and --tls-ca-file arguments. These settings govern all outgoing secure connections from the MCP agent to Grafana APIs (Prometheus, Loki, Dashboards, etc.).

Example (CLI):

bash ./mcp-grafana --tls-ca-file /path/to/ca.crt -debug

Example (Programmatic):

go // Programmatic initialization with TLS grafanaConfig := mcpgrafana.GrafanaConfig{ Debug: true, TLSConfig: &mcpgrafana.TLSConfig{ CertFile: "/path/to/client.crt", CAFile: "/path/to/ca.crt", }, } contextFunc := mcpgrafana.ComposedStdioContextFunc(grafanaConfig)

Server TLS for Streamable HTTP

For securing client connections to the agent when using -t streamable-http, use the distinct --server.tls-cert-file and --server.tls-key-file flags to enable HTTPS on the agent's listening port (e.g., 8443).

Diagnostics and Maintenance

Version Incompatibility Troubleshooting

If datasource operations yield an error similar to:

get datasource by uid : [GET /datasources/uid/{uid}][400] getDataSourceByUidBadRequest ...

This strongly suggests a Grafana installation predating version 9.0, as the required API endpoint was introduced then. Remedy: Upgrade the target Grafana environment to version 9.0 or higher.

Development Workflow

Contributions are encouraged. Setup involves Go toolchain installation.

• Local Execution (STDIO Default): make run
• Local Execution (SSE): go run ./cmd/mcp-grafana --transport sse

Testing Matrix: 1. Unit: make test-unit (Fast, no external services). 2. Integration: make test-integration (Requires local Grafana mock setup via docker-compose up -d). 3. Cloud: make test-cloud (Requires specific Grafana Cloud credentials).

Code Quality: Static analysis is performed via make lint. A custom linter specifically checks for escaped commas (\,) within jsonschema struct tags, which are mandatory to prevent data truncation in schema descriptions.

License

Released under the Apache License, Version 2.0.

Classification Context Note: As a core component of modern organizational infrastructure, this tool falls under the umbrella of business management tools, specifically aiding in the 'control' and 'decision making' aspects by providing immediate, actionable observability data.