Grafana MCP Server

Grafana MCP Server

Available Tools

The following tools are available via the MCP server:

• test_connection: Verify connectivity to your Grafana instance and configuration.
• grafana_promql_query: Execute PromQL queries against Grafana's Prometheus datasource. Fetches metrics data using PromQL expressions, optimizes time series responses to reduce token size.
• grafana_loki_query: Query Grafana Loki for log data. Fetches logs for a specified duration (e.g., '5m', '1h', '2d'), converts relative time to absolute timestamps.
• grafana_get_dashboard_config: Retrieves dashboard configuration details from the database. Queries the connectors_connectormetadatamodelstore table for dashboard metadata.
• grafana_query_dashboard_panels: Execute queries for specific dashboard panels. Can query up to 4 panels at once, supports template variables, optimizes metrics data.
• grafana_fetch_label_values: Fetch label values for dashboard variables from Prometheus datasource. Retrieves available values for specific labels (e.g., 'instance', 'job'). Supports optional metric filtering.
• grafana_fetch_dashboard_variables: Fetch all variables and their values from a Grafana dashboard. Retrieves dashboard template variables and their current values.
• grafana_fetch_all_dashboards: Fetch all dashboards from Grafana with basic information like title, UID, folder, tags, etc.
• grafana_fetch_datasources: Fetch all datasources from Grafana with their configuration details.
• grafana_fetch_folders: Fetch all folders from Grafana with their metadata and permissions.

🚀 Usage & Requirements

1. Get Your Grafana API Endpoint & Service Account Token

1. Ensure you have a running Grafana instance (self-hosted or cloud).
2. Generate a Service Account Token from your Grafana UI:
   • Create Service Account: In your Grafana dashboard, navigate to Admin >> Users & Access >> Service Accounts >> Create a Service Account with Viewer permissions
   • Generate Service Account Key: Within Service Account, create a new Service Account token.
   • Copy the service account token (starts with glsa_)

2. Installation & Running Options

2A. Install & Run with uv (Recommended for Local Development)

2A.1. Install dependencies with uv

2A.2. Run the server with uv

• You can also use uv to run any other entrypoint scripts as needed.
• Make sure your config.yaml is in the same directory as mcp_server.py or set the required environment variables (see Configuration section).

2B. Run with Docker Compose (Recommended for Production/Containerized Environments)

1. Edit grafana-mcp-server/src/grafana_mcp_server/config.yaml with your Grafana details (host, API key).
2. Start the server:
   docker compose up -d
   • The server will run in HTTP (SSE) mode on port 8000 by default.
   • You can override configuration with environment variables (see below).

3. Configuration

The server loads configuration in the following order of precedence:

1. Environment Variables (recommended for Docker/CI):
   • GRAFANA_HOST: Grafana instance URL (e.g. https://your-grafana-instance.com)
   • GRAFANA_API_KEY: Grafana Service Account Token (required)
   • GRAFANA_SSL_VERIFY: true or false (default: true)
   • MCP_SERVER_PORT: Port to run the server on (default: 8000)
   • MCP_SERVER_DEBUG: true or false (default: true)
2. YAML file fallback (config.yaml):
   grafana: host: "https://your-grafana-instance.com" api_key: "your-grafana-api-key-here" ssl_verify: "true" server: port: 8000 debug: true

4. Integration with AI Assistants (e.g., Claude Desktop, Cursor)

You can integrate this MCP server with any tool that supports the MCP protocol. Here are the main options:

4A. Using Docker (with environment variables)

• The -t stdio argument is supported for compatibility with Docker MCP clients (forces stdio handshake mode).
• Adjust the volume path or environment variables as needed for your deployment.

4B. Connecting to an Already Running MCP Server (HTTP/SSE)

If you have an MCP server already running (e.g., on a remote host, cloud VM, or Kubernetes), you can connect your AI assistant or tool directly to its HTTP endpoint.

• Replace your-server-host with the actual host where your MCP server is running.
• For local setup, use localhost as the server host (i.e., http://localhost:8000/mcp).
• Use http for local or unsecured deployments, and https for production or secured deployments.
• Make sure the server is accessible from your client machine (check firewall, security group, etc.).

Health Check

The server runs on port 8000 by default.

5. Project Structure

6. Troubleshooting

Common Issues

1. Connection Failed:
   • Verify your Grafana instance is running and accessible
   • Check your API key has proper permissions
   • Ensure SSL verification settings match your setup
2. Authentication Errors:
   • Verify your API key is correct and not expired
   • Check if your Grafana instance requires additional authentication
3. Query Failures:
   • Ensure datasource UIDs are correct
   • Verify PromQL/Loki query syntax
   • Check if the datasource is accessible with your API key

Debug Mode

Enable debug mode to get more detailed logs:

7. Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

8. License

This project is licensed under the MIT License - see the LICENSE file for details.

9. Support

1. Need help anywhere? Join our discord channel and message on #mcp channel.
2. Want a 1-click MCP Server? Join the same community and let us know.
3. For issues and questions, please open an issue on GitHub or contact the maintainers.