PostgreSQL Performance (read-only)

Name: PostgreSQL Performance (read-only)
Author: gouranshul

作者：gouranshulバージョン 0.1.0i★ –iパソコンで動く

レジストリ名io.github.gouranshul/pg-perf-mcp

インストール

概要

作者による説明（英語の原文）

Read-only PostgreSQL performance diagnostics: slow queries, EXPLAIN, index advice, locks, functions

PopNx MCPの3つの柱

この3つを1つのスコアにまとめることはしません。意見、測定、人気はそれぞれ別のものだからです。

利用者の声iレビューはまだありませんレビューは今後のステップで、アカウント機能と一緒に始まります
私たちの基本チェックi1項目中1項目に合格公開情報からチェック。コードはまだスキャンしていません
利用状況iとても新しい★ –

できること

このサーバーのやさしい解説はまだ書いていません。以下はレジストリから読み取った事実です。

接続方法: パソコンで動く
トランスポート: Streamable HTTP
カテゴリ: データベース・データセット
入力が必要なもの：PGPERF_DB_URL, PGPERF_DB_USER, PGPERF_DB_PASSWORD, MCP_API_KEY

インストール

使っているAIアプリを選んで、設定をコピーしてください。

インストールの前に

基本チェック：1項目中1項目に合格
あなたのパソコンで、あなたのユーザーと同じ権限（ファイル、ネットワーク、アプリ）で動きます。
自分で入力するもの： PGPERF_DB_URL, PGPERF_DB_USER, PGPERF_DB_PASSWORD, MCP_API_KEY

「秘密」と表示された値は、あなたのアカウントの鍵です。絶対に人に教えたり、チャットに貼り付けたりしないでください。

必要なもの

DockerDockerのインストール

どのアプリを使っていますか？

ClaudeClaude CodeCursorVS CodeChatGPT

上でアプリを選んでください。選んだアプリを覚えておくので、次からはボタンに「…にインストール」と表示されます。

Claude Desktop → Settings → Developer → Edit Config を開き、claude_desktop_config.json にこれを貼り付けます

{
  "mcpServers": {
    "pg-perf": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "PGPERF_DB_URL",
        "-e",
        "PGPERF_DB_USER",
        "-e",
        "PGPERF_DB_PASSWORD",
        "-e",
        "MCP_API_KEY",
        "ghcr.io/gouranshul/pg-perf-mcp:0.1.0"
      ],
      "env": {
        "PGPERF_DB_URL": "your-value",
        "PGPERF_DB_USER": "your-value",
        "PGPERF_DB_PASSWORD": "your-value",
        "MCP_API_KEY": "your-value"
      }
    }
  }
}

ターミナルでこれを実行します

claude mcp add pg-perf --env PGPERF_DB_URL=your-value --env PGPERF_DB_USER=your-value --env PGPERF_DB_PASSWORD=your-value --env MCP_API_KEY=your-value -- docker run -i --rm -e PGPERF_DB_URL -e PGPERF_DB_USER -e PGPERF_DB_PASSWORD -e MCP_API_KEY ghcr.io/gouranshul/pg-perf-mcp:0.1.0

動かす前に、空欄の値を入力してください。

Cursorで開く

または、設定を自分でコピーする

プロジェクトの .cursor/mcp.json、または ~/.cursor/mcp.json に貼り付けます

{
  "mcpServers": {
    "pg-perf": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "PGPERF_DB_URL",
        "-e",
        "PGPERF_DB_USER",
        "-e",
        "PGPERF_DB_PASSWORD",
        "-e",
        "MCP_API_KEY",
        "ghcr.io/gouranshul/pg-perf-mcp:0.1.0"
      ],
      "env": {
        "PGPERF_DB_URL": "your-value",
        "PGPERF_DB_USER": "your-value",
        "PGPERF_DB_PASSWORD": "your-value",
        "MCP_API_KEY": "your-value"
      }
    }
  }
}

ブラウザがアプリを開いてよいか確認し、そのあとアプリが設定を表示して確認を求めます。キーの値は空欄のままなので、自分で入力してください。

VS Codeで開く

または、設定を自分でコピーする

プロジェクトの .vscode/mcp.json に貼り付けます

{
  "servers": {
    "pg-perf": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "PGPERF_DB_URL",
        "-e",
        "PGPERF_DB_USER",
        "-e",
        "PGPERF_DB_PASSWORD",
        "-e",
        "MCP_API_KEY",
        "ghcr.io/gouranshul/pg-perf-mcp:0.1.0"
      ],
      "env": {
        "PGPERF_DB_URL": "your-value",
        "PGPERF_DB_USER": "your-value",
        "PGPERF_DB_PASSWORD": "your-value",
        "MCP_API_KEY": "your-value"
      }
    }
  }
}

これはパソコンで動くサーバーですが、ChatGPTがつなげるのはインターネット上のサーバーだけです。ほかのアプリを選んでください。

選んだアプリは、この端末のCookieに保存されます。アカウントは不要です。

自分で入力する値

PGPERF_DB_URL 必須 env
JDBC URL of the database to diagnose. From inside the container, use host.docker.internal for a database on your machine, e.g. jdbc:postgresql://host.docker.internal:5432/mydb
PGPERF_DB_USER 必須 env
A read-only role with pg_read_all_stats and pg_monitor (see docker/init.sql)
PGPERF_DB_PASSWORD 秘密必須 env
Password of that role
MCP_API_KEY 秘密必須 env
Bearer token clients must send, at least 16 characters (32+ random recommended)

この設定は、作者のレジストリ登録情報から作成しています。READMEと違う場合は、READMEに従ってください。

できること

パソコンで動くサーバーです。インストールすると、ツール一覧がAIアプリに表示されます。

基本チェックi

誰でも見られる情報をチェックしており、コードは読んでいません。当てはまらない項目は数に入れていません。 · 2026年11月8日にチェック

✓ 合格
作者とリポジトリが一致
レジストリ名は、リポジトリを所有するGitHubアカウント gouranshul で確認済みです
… 未チェック
今もメンテナンスされている
このリポジトリはまだGitHubから読み取っていません
… 未チェック
ライセンスがある
このリポジトリはまだGitHubから読み取っていません
– 対象外
エンドポイントが応答する
これはパソコンで動くため、インターネット上のエンドポイントはありません
– 対象外
OAuthでサインイン
パソコンで動き、代わりにローカルの設定を使います
… 未チェック
ツールの説明に隠れた指示がない
パソコンで動くサーバーです。ツール一覧を読み取れるのは、インターネット上のエンドポイントがある場合だけです

データベース・データセットのほかのサーバーとの比較i

このカテゴリのほかの1144件のうち0%よりスターが多い
このカテゴリのほかの1144件のうち63%より最近レジストリに公開
基本チェックの結果が、このカテゴリのほかの1144件のうち100%と同じかそれ以上

レジストリでこのカテゴリにある有効なすべてのサーバーと比較しています。スターは、公開者がリポジトリの所有者である場合だけ数えます。

よくある質問

PostgreSQL Performance (read-only)は安全ですか？

当てはまる基本チェック1項目のうち1項目に合格しました。コードは読んでいません。キーやトークンを追加する前に、サーバーがどんなアクセスを求めているかを確認し、必要な権限だけを持つキーを使ってください。

どんなキーやコードが必要ですか？

入力が必要なもの：PGPERF_DB_URL, PGPERF_DB_USER, PGPERF_DB_PASSWORD, MCP_API_KEY

パソコンで動きますか、それともクラウドですか？

あなたのパソコンで動きます。必要なときにAIアプリが起動し、データは作者のサーバーを通りません（サーバー自体がオンラインサービスを呼び出す場合を除きます）。

今もメンテナンスされていますか？

GitHubリポジトリの最終更新は–、最新バージョン（0.1.0）がレジストリに届いたのは29 日前です。

どのアプリで使えますか？

Claude Desktop、Claude Code、Cursor、VS CodeなどのMCP対応アプリで使えます。パソコンにDockerも必要です。

代わりに使えるものは？

同じカテゴリには：Supabase, MongoDB MCP Server, Elasticsearch MCP Server

代わりの候補

同じカテゴリで、ほかの作者が作ったサーバー。スターの多い順。

カードの見方：↓ 週あたりのダウンロードi★ GitHubスターi3つの柱：レビュー · チェック · 利用状況i更新＝最新バージョンをレジストリに公開した日i

Supabase

MCP server for interacting with the Supabase platform

作者：supabase広く使われている↓ 23.5万/週★ 2993一昨日更新

パソコンでもクラウドでも✓ supabase.com

インストール

MongoDB MCP Server

MongoDB Model Context Protocol Server

作者：mongodb-js広く使われている↓ 15.7万/週★ 11574 日前更新

パソコンで動く

インストール

Elasticsearch MCP Server

MCP server for interacting with Elasticsearch

作者：cr7258成長中↓ 2711/週★ 31514 か月前更新

パソコンで動く

インストール

作者のREADME

READMEを開く

作者のリポジトリから書かれたとおりにコピーしたものです。PopNx MCPは内容を確認・推奨していません。HTML、画像、スクリプトは取り除いています。リンクはこのサイトの外へ移動します。

pg-perf-mcp

An MCP server that lets AI assistants diagnose PostgreSQL performance problems safely: slow queries, EXPLAIN plans, index suggestions, table health and lock contention. It is read-only by design.

*A real Claude Code session against the demo shop, sped up. First it finds which database functions are slow and why. Then it explains a slow catalog query and estimates the fix with a hypothetical index. Asked to create the index, it says it can't: every tool is read-only.*

Why

When a page is slow, developers paste a query into a chat and ask "why is this slow?". The assistant then guesses, because it cannot see the plan, the table sizes, the existing indexes or which queries actually dominate the load.

pg-perf-mcp gives the assistant real numbers from `pg_stat_statements`, `EXPLAIN` and the catalogs, through a narrow, audited, read-only interface. It cannot change data, cannot run DDL, and never creates the indexes it recommends.

Demo

A condensed, illustrative session against the demo shop (docker compose up, then ./demo/workload.sh). Exact numbers vary from run to run:

You:    The shop database feels slow. What's going on?

Claude: [top_slow_queries orderBy=total_time] The top statement by total time is SELECT id, status, total, created_at FROM shop.orders WHERE customer_id = $1 ORDER BY created_at DESC (thousands of calls, the largest share of total execution time).

[explain_query sql="... WHERE customer_id = 42 ORDER BY created_at DESC"] HIGH SEQ_SCAN_ON_LARGE_TABLE Seq Scan on shop.orders reads all ~1.0M rows of shop.orders to apply filter (customer_id = 42); only a handful match.

[suggest_indexes] CREATE INDEX CONCURRENTLY idx_orders_customer_id ON shop.orders (customer_id); hypopg: the planner would use it; estimated cost drops by well over 90%. Not executed. Review it and run it yourself, ideally off-peak.

[table_health table=shop.orders] Autovacuum is disabled on shop.orders and ~20% of rows are dead. Re-enable autovacuum and VACUUM.

Prioritized actions: 1) add the index above (orders.customer_id is a foreign key with no index),

re-enable autovacuum on shop.orders, 3) ...

Architecture

flowchart LR

A["AI assistant (Claude Code, Claude Desktop, ...)"] -- "MCP over streamable HTTP Authorization: Bearer key" --> F["API key filter (constant-time)"] F --> M["MCP tools / resources / prompt Spring AI 2.0 annotations"] M --> R["ToolRunner audit log · metrics · safe errors"] R --> G["SqlGuard PG lexer + JSqlParser"] G --> E["ReadOnlyExecutor READ ONLY tx · always rollback statement/lock timeout · row cap"] R --> AN["analysis PlanAnalyzer · IndexAdvisor (pure functions)"] E --> P[("PostgreSQL 18 role mcp_readonly pg_stat_statements · hypopg")]

Tools

Tool	What it does	Safety notes
`top_slow_queries`	Most expensive statements from `pg_stat_statements`: normalized text, calls, total/mean/max ms, rows, cache hit ratio, share of total time. Order by `total_time`, `mean_time`, `calls` or `rows`.	Fixed SQL; sort column chosen from an enum. Excludes the server's own statements.
`explain_query`	Summarized plan: 5 costliest nodes, seq scans on large tables, 10x row misestimates, disk sorts/hash spills, nested loops with many iterations. `analyze=true` adds real timings. `$1` placeholders get a generic plan.	SQL guard first. ANALYZE runs in a read-only transaction that is rolled back and cancelled after the timeout.
`suggest_indexes`	`CREATE INDEX CONCURRENTLY` candidates from filtered seq scans, join keys and `ORDER BY ... LIMIT`, each with a reason; validated with hypothetical indexes when `hypopg` is installed.	Never executed. Hypothetical indexes are reset in a savepoint so they cannot leak to other calls.
`unused_indexes`	Indexes with `idx_scan = 0`, largest first, excluding primary key, unique and constraint indexes; includes size, definition and a `DROP INDEX CONCURRENTLY` to review.	Nothing is dropped. Reports when stats were last reset.
`table_health`	Live/dead tuples, dead ratio, last (auto)vacuum/analyze, rows changed since analyze, seq vs index scans, sizes, with plain-language warnings.	Catalog reads only.
`blocking_sessions`	Blocked/blocking pairs via `pg_blocking_pids`, truncated query texts, wait time, lock type/mode/table, blocker state, root blockers.	Never cancels or terminates anything.
`slow_functions`	User-defined functions (PL/pgSQL, SQL, ...) ranked by total, self or mean time or calls, from `pg_stat_user_functions`, with language and volatility.	Catalog reads only. Needs `track_functions`.
`explain_function`	Looks inside the functions a query calls: time per function, every statement executed inside them with calls, time and its own analyzed plan, and findings such as a seq scan inside a function, a function called once per row, or a read-only function left `VOLATILE`. Includes the function source.	SQL guard first; runs in the same rolled-back read-only transaction as `explain_query`, so functions that write fail. `auto_explain` is switched on for that transaction only, with generic plans so no data values appear.

Resources: pg://schema/overview (tables, row estimates, sizes, indexes) and pg://schema/{table} (columns, indexes with scan counts, foreign keys flagged when unindexed). Prompt: diagnose_slow_database, a guided workflow: slow queries, then explain, suggest indexes, table health, functions, then a prioritized summary.

Why a separate tool for database functions

EXPLAIN shows a function call as one opaque expression, and charges its time to whichever plan node evaluates it. On the demo catalog page (20 products, each calling shop.product_rating), explain_query blames the index scan on products (184 ms self time) and finds nothing else serious. explain_function on the same query, against the full demo data:

shop.product_rating          plpgsql  20 calls  99% of execution time

SELECT avg(rating) FROM shop.reviews WHERE product_id = p_product_id 20 calls 175 ms 96% of execution time HIGH FUNCTION_DOMINATES_QUERY shop.product_rating takes 99% of the query's execution time HIGH FUNCTION_CALLED_PER_ROW ran 20 times for one query (9.0 ms per call) HIGH SEQ_SCAN_ON_LARGE_TABLE inside shop.product_rating: Seq Scan on shop.reviews reads all ~250k rows to apply filter (reviews.product_id = $1)

How it works (ADR 0006): the query runs once with auto_explain enabled for that transaction only, so the plan of each nested statement comes back as a notice; per-function time comes from pg_stat_xact_user_functions and per-statement calls from pg_stat_statements, both as before/after differences.

Security model

Five independent layers stand between the assistant and a write (details in ADR 0001):

SQL guard: exactly one plain SELECT. It is checked by a PostgreSQL-faithful lexer *and* JSqlParser, and both must agree. Blocks DML/DDL, multiple statements, data-modifying CTEs, SELECT INTO, FOR UPDATE/SHARE, COPY, DO, and dangerous functions (pg_sleep*, *_file, lo_*, dblink*, set_config, pg_terminate_backend, query_to_xml, ...). It fails closed.
Read-only role: mcp_readonly has SELECT plus pg_read_all_stats/pg_monitor, with default_transaction_read_only = on and statement_timeout = 5s set on the role.
Read-only connections: Hikari readOnly=true and a read-only session default.
One rolled-back read-only transaction per call: statement_timeout/lock_timeout set locally, standard_conforming_strings forced on, always rolled back.
Row cap: every result is capped (default 200 rows).

Around those layers: a bearer API key (constant-time comparison; only /actuator/health is open), a JSON audit line per call (SQL stored as a SHA-256 hash plus an 80-character preview), error messages with no stack traces or connection details, and metrics mcp.tool.duration and mcp.guard.rejections.

Quickstart

Requirements: Docker. There are two ways to start:

[Use it on your database](#use-it-on-your-database): pull the published image. No clone or build.
[Try the demo shop](#try-the-demo-shop): clone the repo and get a seeded database with realistic problems to diagnose.

Either way, finish with connecting your AI client.

Use it on your database

1. Pull the image (public on GHCR, built for amd64 and arm64):

docker pull ghcr.io/gouranshul/pg-perf-mcp:0.1.0

2. Prepare the database (once). Create a read-only role like mcp_readonly (see docker/init.sql) and make sure pg_stat_statements is in shared_preload_libraries. Prefer a replica or staging database: analyze=true and explain_function execute the query. For the function tools, also enable function tracking.

3. Run it. Put the settings in a file so secrets stay out of your shell history:

cat > pg-perf.env <<'EOF'

PGPERF_DB_URL=jdbc:postgresql://host.docker.internal:5432/mydb PGPERF_DB_USER=mcp_readonly PGPERF_DB_PASSWORD= MCP_API_KEY=<32+ random characters> EOF

docker run --rm --env-file pg-perf.env -p 127.0.0.1:8080:8080 ghcr.io/gouranshul/pg-perf-mcp:0.1.0

host.docker.internal reaches a database on your machine (Docker Desktop; on Linux add --add-host=host.docker.internal:host-gateway). The MCP endpoint is now http://localhost:8080/mcp.

4. Connect your AI client: see below.

Try the demo shop

To build and test from source you also need Java 25.

git clone https://github.com/gouranshul/pg-perf-mcp && cd pg-perf-mcp

cp .env.example .env # then replace the placeholder secrets docker compose up --build # Postgres 18 + seeded demo shop (~4.5M rows) + the MCP server on :8080

Generate some slow-query statistics (optional, but makes top_slow_queries interesting):

./demo/workload.sh          # 60s of deliberately bad queries via pgbench

./demo/lock-scenario.sh # holds a row lock for 2 minutes so blocking_sessions has something to show ./demo/smoke-test.sh # curl-based end-to-end check of health, auth and two tool calls

Connect from Claude Code

claude mcp add --transport http pg-perf http://localhost:8080/mcp --header "Authorization: Bearer $MCP_API_KEY"

In PowerShell, set the key first, or the header goes out empty and the server answers 401:

$env:MCP_API_KEY = "<your MCP_API_KEY>"

claude mcp add --transport http pg-perf http://localhost:8080/mcp --header "Authorization: Bearer $env:MCP_API_KEY"

Or install it as a Claude Code plugin. Claude Code asks for the endpoint (default http://localhost:8080/mcp) and your MCP_API_KEY, which it keeps in secure storage:

/plugin install pg-perf --marketplace gouranshul/pg-perf-mcp

On Claude Code versions before 2.1.275, add the marketplace first: `/plu

冒頭だけを表示しています。続きはリポジトリで読めます

PostgreSQL Performance (read-only)

概要

PopNx MCPの3つの柱

できること

インストール

インストールの前に

自分で入力する値

できること

基本チェックi

作者とリポジトリが一致

今もメンテナンスされている

ライセンスがある

エンドポイントが応答する

OAuthでサインイン

ツールの説明に隠れた指示がない

データベース・データセットのほかのサーバーとの比較i

よくある質問

代わりの候補

Supabase

MongoDB MCP Server

Elasticsearch MCP Server

作者のREADME

pg-perf-mcp

Why

Demo

Architecture

Tools

Why a separate tool for database functions

Security model

Quickstart

Use it on your database

Try the demo shop

Connect from Claude Code