PMM MCP Server

A community-maintained Model Context Protocol server for Percona Monitoring and Management (PMM 2.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 design: works with a Grafana Viewer token; the server never writes to PMM
• 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

Linux / macOS

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

Windows (PowerShell)

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

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

Set these environment variables (see pmm.env.example):

🛠️ Available Tools

Inventory

Query Analytics

Metrics

💬 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; the server never writes to PMM.
• 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

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