# 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

```bash
uv venv .venv
source .venv/bin/activate
uv sync
```

#### 2A.2. Run the server with uv

```bash
uv run -m src.grafana_mcp_server.mcp_server
```

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

```json
{
  "mcpServers": {
    "grafana": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "GRAFANA_HOST",
        "-e",
        "GRAFANA_API_KEY",
        "-e",
        "GRAFANA_SSL_VERIFY",
        "drdroidlab/grafana-mcp-server",
        "-t",
        "stdio"
      ],
      "env": {
        "GRAFANA_HOST": "https://your-grafana-instance.com",
        "GRAFANA_API_KEY": "your-grafana-api-key-here",
        "GRAFANA_SSL_VERIFY": "true"
      }
    }
  }
}
```

- 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.

```json
{
  "mcpServers": {
    "grafana": {
      "url": "http://your-server-host:8000/mcp"
    }
  }
}
```

- 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

```bash
curl http://localhost:8000/health
```

The server runs on port 8000 by default.

---

## 5. Project Structure

```
grafana-mcp-server/
│   └── src/
│       └── grafana_mcp_server/
│           ├── __init__.py
│           ├── config.yaml              # Configuration file
│           ├── mcp_server.py            # Main MCP server implementation
│           ├── stdio_server.py          # STDIO server for MCP
│           └── processor/
│               ├── __init__.py
│               ├── grafana_processor.py # Grafana API processor
│               └── processor.py         # Base processor interface
├── tests/
├── Dockerfile
├── docker-compose.yml
├── pyproject.toml
└── README.md
```

---

---

## 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:

```bash
export MCP_SERVER_DEBUG=true
```

---

## 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](LICENSE) file for details.

---

## 9. Support

1. Need help anywhere? Join our [discord channel](https://discord.gg/GTzfNMSm) 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.