What the Grafana MCP server does
The Grafana MCP server gives an AI client a controlled way to work with a Grafana instance. Instead of moving between a chat and dashboards by hand, you can ask an agent to find dashboards, inspect metrics and logs, work with alert rules, or create links to Grafana resources. The official server supports self-hosted Grafana and Grafana Cloud.
This is useful when the question has operational context: "what changed after the deploy?", "which dashboard tracks checkout latency?", or "show me the alerts that are firing." The agent still needs the same Grafana permissions as the credentials you give it. MCP changes the interface, not the access model.
Grafana maintains the open-source mcp-grafana repository and its setup documentation. The quickest local route uses uvx; Docker, a binary, and Helm are also supported.
Before you connect it
You need a Grafana URL and credentials with only the permissions your intended tools require. A service account token is a sensible default for most setups because it is revocable and can be scoped. Do not paste an administrator token into a desktop client configuration just because it is convenient.
For full datasource-related functionality, Grafana documents Grafana 9.0 or later as the baseline. Older instances can still expose a confusing failure mode because endpoints used for datasource operations are not present.
If your AI client launches local MCP processes, install uv first. If it does not, use the Docker or remote transport options in the official documentation instead of trying to force a local configuration into a hosted client.
Install with Claude Desktop or Cursor
The official quick start runs the server through uvx, so there is no separate repository clone or package installation step. Put the following server entry in the MCP configuration format your client uses:
{
"mcpServers": {
"grafana": {
"command": "uvx",
"args": ["mcp-grafana"],
"env": {
"GRAFANA_URL": "https://your-instance.grafana.net",
"GRAFANA_SERVICE_ACCOUNT_TOKEN": "your-service-account-token"
}
}
}
}
For a local instance, set GRAFANA_URL to its reachable URL, such as http://localhost:3000. Restart the client after saving its configuration, then look for the Grafana tools in its tool picker. If the client reports that it cannot spawn mcp-grafana, use the full binary path when you installed the binary rather than uvx.
The server is a good fit for Claude Desktop and Cursor when those clients are configured to run stdio MCP servers. Client support depends on the client version and its local-process policy, so start with Grafana's client configuration examples rather than copying a generic MCP snippet from an old post.
Docker setup, and the transport gotcha
Docker is useful when you want a reproducible local runtime or cannot use uvx. For a direct desktop-client connection, run the image in stdio mode:
docker run --rm -i \
-e GRAFANA_URL=https://your-instance.grafana.net \
-e GRAFANA_SERVICE_ACCOUNT_TOKEN=your-service-account-token \
grafana/mcp-grafana -t stdio
Then configure your client to invoke docker with the same arguments and environment variables. The -i option matters because the client speaks over standard input and output.
Here is the practical setup distinction worth checking before you troubleshoot for an hour: the official Docker image defaults to SSE, while Claude Desktop and similar local clients usually need stdio. Add -t stdio for a local client. If you intentionally want a network service, expose port 8000 and use the server's SSE or streamable HTTP transport instead. The official Docker instructions show both patterns.
What you can ask an agent to do
The exact tool list evolves with the server, but Grafana documents access across dashboards, metrics, logs, alert rules, incidents, Sift, and resource deeplinks. That makes it more than a dashboard search connector. It can support an investigation that starts with a symptom and moves through signals.
Good first prompts are narrow and read-oriented:
- Find dashboards that contain a panel for API latency.
- Summarize error-rate changes in the last hour and link the relevant dashboard.
- List firing alerts for the production environment.
- Search logs for a request ID and identify the service that produced the errors.
Start with read access and a small set of prompts. If your environment allows writes, make the agent state the intended change and wait for confirmation. A tool that can edit alert rules is not automatically a safe automation policy.
Quality signals and the MCPVault listing
MCPVault tracks grades as public maintenance, adoption, license, and documentation signals. Read how MCPVault quality grades work before treating a letter as a security audit. A grade is a fast comparison aid, not a guarantee that a server should receive production credentials.
There is an important naming detail here. The live MCP Grafana listing on MCPVault is an auto-indexed, unclaimed TypeScript and npm implementation by 0xteamhq, with 43+ declared tools and a current C grade. It is not the Go implementation maintained in Grafana's official repository. Compare the repository owner, transport, and credential model before installing a server simply because it has a familiar name.
That distinction is useful when browsing the wider MCP server directory. Similar names can describe independent implementations, and an unclaimed listing has not been reviewed by its maintainer. For a production observability connection, favor an official upstream or a listing whose owner has claimed and verified it.
Troubleshooting checklist
The server starts but no tools appear
First confirm that your client supports local stdio MCP servers and that it was restarted after the configuration change. Then run the same command in a terminal. A working terminal command narrows the problem to the client's configuration path or environment handling.
The server cannot connect to Grafana
Check that GRAFANA_URL points to the actual instance URL and that the service account token was copied without whitespace. Grafana Cloud URLs normally use the instance hostname, not localhost. If you are behind a proxy, also verify that the process can reach the URL from where it runs.
Datasource operations fail
Confirm the Grafana version first. Grafana documents version 9.0 or later for full functionality because datasource operations depend on newer API endpoints. After that, check whether the service account has the permissions required for the datasource and folder you are querying.
Frequently Asked Questions
Does the Grafana MCP server work with Claude Desktop?
Yes, the official server provides a Claude Desktop configuration using uvx and stdio. Claude Desktop must be able to run local processes, and you need to restart it after changing the MCP configuration.
Can I use the Grafana MCP server with Grafana Cloud?
Yes. Set GRAFANA_URL to your Grafana Cloud instance URL and provide a service account token with appropriate permissions. The official documentation uses a https://your-instance.grafana.net style URL in its examples.
Why does the Docker version not work with my desktop client?
The Docker image defaults to SSE. For a desktop client that communicates over stdio, include both -i and -t stdio in the Docker command. Use the network transports only when your client is configured to connect to them.
Is the MCPVault Grafana listing the official Grafana server?
No. The current MCP Grafana listing points to a separate auto-indexed implementation. The official project is maintained at grafana/mcp-grafana on GitHub, so check the repository before connecting credentials.
Your server in the vault.
If you built an MCP server, claim the listing so developers can identify the maintained project, set compatibility, and see accurate details. Verification is free during early access and requires the MCPVault badge to remain visible in your README or project site.
Claim your listing or submit a server if it is not indexed yet.