PMM MCP Server

A community-maintained Model Context Protocol server for Percona Monitoring and Management (PMM 2.x and 3.x). It gives Claude and other MCP clients access to MySQL, MongoDB and PostgreSQL metrics (PromQL), Query Analytics (slowest queries, query details, ClickHouse SQL), alerts and PMM dashboards. It is read-only by default; a few write tools (silences, annotations) can be enabled explicitly, see Read-only or write?.

This is not an official Percona or Anthropic product.

✨ Features

• Read-only by default: works with a Grafana Viewer token. Optional write tools (silences, annotations) are off unless PMM_ALLOW_WRITE=1 and always dry-run first

• Metrics: instant and range PromQL queries plus label discovery

• Query Analytics (QAN): top queries, per-service load, single-query details and distribution over time

• Safe SQL: free-form SELECT against QAN's ClickHouse, strictly validated and capped

• TLS verified by default, with custom CA bundle support

• Cross-platform: Linux, macOS and Windows, with one-command installers

Related MCP server: mcp-read-only-sql

🚀 Installation

Requirements

• Python 3.11+ and uv

• Network access to your PMM server (VPN if needed)

• A PMM Grafana token: Administration → Service accounts → role Viewer → Add token

With uvx (no clone needed)

uvx pmm-mcp

Put PMM_URL and PMM_TOKEN in the environment (or an env file, see Configuration). To register it with Claude Code:

claude mcp add pmm -- uvx --env-file ~/.config/mcp/pmm.env pmm-mcp

Linux / macOS (installer)

git clone https://github.com/hakkiburakalks/pmm-mcp && cd pmm-mcp && ./install.sh

Windows (PowerShell installer)

git clone https://github.com/hakkiburakalks/pmm-mcp; cd pmm-mcp; powershell -ExecutionPolicy Bypass -File .\install.ps1

The installer asks for your PMM URL and token, stores them in ~/.config/mcp/pmm.env (owner-only access) and registers the server with Claude Code under the name pmm. If claude is not installed, it prints the JSON snippet for Claude Desktop instead.

🎯 Quick Start

Claude Desktop / any MCP client

The server is a plain stdio MCP server. Run it with:

uv run --env-file /path/to/pmm.env --directory /path/to/pmm-mcp pmm-mcp

(server.py still works as an alias for existing setups) and register that command in your client, for example in claude_desktop_config.json:

{
  "mcpServers": {
    "pmm": {
      "command": "uv",
      "args": [
        "run", "--quiet",
        "--env-file", "C:\\Users\\you\\.config\\mcp\\pmm.env",
        "--directory", "C:\\path\\to\\pmm-mcp",
        "server.py"
      ]
    }
  }
}

Use the full path to uv as command if your client does not inherit your PATH.

On macOS the config file is ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "pmm": {
      "command": "/opt/homebrew/bin/uv",
      "args": [
        "run", "--quiet",
        "--env-file", "/Users/you/.config/mcp/pmm.env",
        "--directory", "/Users/you/pmm-mcp",
        "server.py"
      ]
    }
  }
}

Desktop apps don't inherit your shell PATH, so give the full path to uv (check with which uv; typically /opt/homebrew/bin/uv on Apple Silicon, /usr/local/bin/uv on Intel, ~/.local/bin/uv expanded to an absolute path if installed via the curl script). install.sh prints this snippet for you.

Claude Code

claude mcp add pmm -- uv run --quiet --env-file ~/.config/mcp/pmm.env --directory /path/to/pmm-mcp server.py

🔧 Configuration

Create ~/.config/mcp/pmm.env (the installers do this for you) with your own values; the ones below are fake:

PMM_URL=https://pmm.example.com
PMM_TOKEN=glsa_EXAMPLEexampleEXAMPLEexample1234567890_abcdef12
PMM_VERIFY=1
# PMM_CA_BUNDLE=/etc/ssl/certs/my-company-ca.pem
# PMM_ALLOW_WRITE=1   # off by default, see "Read-only or write?" below

Set these environment variables (see pmm.env.example for a commented template):

🛠️ Available Tools

Inventory

Alerting

Query Analytics

Metrics

Dashboards and context

Read-only or write?

Read-only is the default and the recommended setup. With just PMM_URL and a Viewer PMM_TOKEN the model can look at metrics, queries, alerts and dashboards but cannot change anything. To let it silence an alert during maintenance or add a deploy marker, you need all three of: an Editor/Admin token, PMM_ALLOW_WRITE=1, and your approval of each call. Creating alert rules is not supported.

Write tools (opt-in)

Registered only when PMM_ALLOW_WRITE=1 and the token has Editor/Admin rights. Without the flag the model does not even see them.

Every write tool is a dry run by default: it returns exactly what it would do and changes nothing until it is called again with confirm=true. The tools are also annotated as non-read-only, so MCP clients ask for approval. The model is instructed to confirm with you first, so keep your client's per-tool approval on for these.

💬 Example Queries

Overview

• "Which databases does PMM monitor, and are they all healthy?"

• "Which service spends the most time running queries?"

Query Analytics

• "Show the 10 slowest queries on the production MySQL service"

• "Give me the details and time distribution of this query ID"

Metrics

• "What is the connection count on db-prod-1 over the last 6 hours?"

• "Compare InnoDB buffer pool hit ratio across all MySQL nodes"

🔒 Security

• Use a Viewer token unless you need the write tools; by default the server never writes to PMM. Writes require PMM_ALLOW_WRITE=1, an Editor/Admin token and confirm=true on each call.

• TLS certificates are verified by default.

• pmm_qan_sql accepts only a single plain SELECT/WITH. Comments, quoted identifiers, SETTINGS/FORMAT/INTO, table functions (url, file, remote, ...) and system tables are rejected. Row counts and time windows are capped.

• Tool inputs (labels, service types, limits, time windows) are validated before being used in a query.

• The token lives in ~/.config/mcp/pmm.env, created with owner-only permissions. Never commit it.

See SECURITY.md to report a vulnerability.

🐛 Troubleshooting

🔍 Debugging

Launch the server in the MCP Inspector:

npx @modelcontextprotocol/inspector uv run --env-file /path/to/pmm.env --directory /path/to/pmm-mcp server.py

🧪 Development

uv sync --extra dev
uv run pytest

📝 Notes

• Tested against PMM 2 (Grafana 9.2) and PMM 3 (Grafana 12.4) with the default datasource UIDs, using Viewer and Admin tokens, and QAN on MySQL, PostgreSQL (pg_stat_statements) and MongoDB (profiler). Not covered: alerts in firing state, ProxySQL/HAProxy.

• PMM's /v1 API rejects Viewer tokens (observed on PMM 2; PMM 3 was not checked for this), so everything goes through the Grafana datasource proxy.

• The same queryid can appear in several services; group by service when aggregating.

• In MySQL QAN the max_ms/p99 fields are 0 (a perfschema limitation).

📄 License

MIT: free for anyone to use, modify and distribute, including commercially.