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 read-only access to MySQL, MongoDB and PostgreSQL metrics (PromQL) and Query Analytics (slowest queries, query details, ClickHouse SQL).

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

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