Multigres

multigres-mcp

An MCP server for Multigres clusters. It gives an MCP client two groups of tools:

• Postgres diagnostics through the Multigres gateway: schemas and objects, read-only SQL, query plans with hypothetical indexes, top queries, index advice and a health check. These follow the tools of postgres-mcp.
• Cluster tools through multiadmin: cluster status, backups, node logs, and in the unrestricted mode switching the primary and starting or expiring backups.

The server is read-only by default. Write tools are registered only in the unrestricted mode.

It has been tested against a local Multigres Docker cluster built from commit 5fa0f2955ede (2026-11-10, PostgreSQL 17.7, two cells) on Linux with Docker Engine. Other setups have not been tested.

Install

Each release has a multigres-mcp- .mcpb file. It is an MCP Bundle: clients that install bundles ask for the settings under "Configuration" and run the server. It is also a zip file whose server/ directory holds binaries for Linux and macOS on amd64 and arm64 and for Windows on amd64, which any other client can run directly.

Build

Requires Go 1.26 or later.

git clone https://github.com/JoongHyuk-Shin/multigres-mcp

cd multigres-mcp go build -o multigres-mcp ./cmd/multigres-mcp

The server talks MCP over standard input and output. ./multigres-mcp --help prints the options.

packaging/build-mcpb.sh builds the release bundle into dist/. It also needs jq, Node.js and openssl.

Configuration

Every option can be given as a flag or as an environment variable. A flag wins over the variable.

Direct node connections reuse the user, password and database of --database-url and take the host and port from multiadmin.

In the local Docker cluster both nodes report the host localhost, while their Postgres ports are reachable only at the container's address. Find that address in the Multigres checkout with:

docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' "$(docker compose ps -q multigres)"

and pass it as --node-host-map localhost= .

Adding it to an MCP client

With Claude Code, for the local Docker cluster (replace 172.18.0.2 with the address found above):

claude mcp add multigres -e DATABASE_URI=postgres://postgres:postgres@localhost:15432/postgres -- /path/to/multigres-mcp --admin-url http://localhost:15000 --node-host-map localhost=172.18.0.2

Other clients take the same command, arguments and environment in their server configuration, for example:

{

"mcpServers": { "multigres": { "type": "stdio", "command": "/path/to/multigres-mcp", "args": ["--admin-url", "http://localhost:15000", "--node-host-map", "localhost=172.18.0.2"], "env": { "DATABASE_URI": "postgres://postgres:postgres@localhost:15432/postgres" } } } }

Tools

That is 14 tools in the restricted mode and 19 in the unrestricted mode, or 9 and 10 without --admin-url. diagnose and get_top_queries take an optional node to read one node directly instead of through the gateway, for example the old primary after a failover.

Safety

The restricted mode does not register any tool that can write. Writing SQL is a tool of its own, execute_write_sql, so a client permission given to execute_sql never covers a write, even after the server is restarted in the unrestricted mode.

Every statement that execute_sql, explain_query and analyze_query_indexes receive passes these checks. They do not rely on each other: checks 1, 3 and 4 each stop a write on their own.

1. It is parsed with the Multigres parser. It must be exactly one statement, the top statement must be SELECT, EXPLAIN of a SELECT, or SHOW, and the tree must not contain data-changing statements, SELECT INTO or locking clauses. Functions must be on an allow list (the postgres-mcp list with functions that have side effects removed), and a schema-qualified function must be in pg_catalog.
2. It is sent with the extended query protocol, which carries one statement only.
3. The read-only connection is opened with default_transaction_read_only=on.
4. It runs in BEGIN TRANSACTION READ ONLY, which is always rolled back.
5. search_path is pinned, and a statement that calls an unqualified function whose name also exists outside pg_catalog is not sent.
6. A statement timeout is set.

This covers the statements the model sends and the functions they call directly. The bodies of objects already in the database (views, functions, operators, policies) are trusted and not checked. Against a production database, connect as a read-only role as well. cluster_status shows whether the connected user is a superuser.

Multigres hands pooled Postgres connections from one client to the next. Within the same transaction, the server removes the hypothetical indexes and session advisory locks a tool call may have left on its connection. If that cleanup fails, it ends its own Postgres session rather than hand the state on. execute_write_sql rejects transaction control, session-level SET and RESET, multigres.* settings, hypopg functions, and statements that leave session state behind (temporary objects, PREPARE, LISTEN, DECLARE ... WITH HOLD, LOAD, DISCARD, DO). Session settings (set_config(..., false)) and the random seed (setseed) changed inside the body of a function or trigger are not removed and can reach the next client of that connection; like the other object bodies, they are trusted.

Direct node connections run fixed queries only, never SQL from the model.

The multiadmin address (in full and as host:port), the admin token and the database password are removed from tool results and error messages. The removal replaces text, so a password that is a common word is masked wherever that word appears. A password equal to the user or database name is not masked, because results show those names; the server prints a warning when it starts.

Things to know

• --sql-timeout defaults to 25s because the multipooler ends a transaction's connection when one statement runs past --connpool-user-reserved-inactivity-timeout (default 30s). To use a longer timeout, raise that pooler setting too.
• The results of execute_sql and execute_write_sql end with a line naming the settings the server set for that call only (statement_timeout, lock_timeout, and for reads search_path), and the statement_timeout its own session had before. The gateway enforces statement_timeout itself without setting it on the node, so the node's pg_settings shows 0 for it while SHOW through the gateway answers with the gateway's value.
• Cumulative statistics are kept per node. After a failover the new primary's statistics do not include what happened on the old primary. The tools that use statistics start with the period they cover; the node option of diagnose and get_top_queries reads another node.
• Index sizes in the advice are hypopg estimates and ignore btree deduplication. On a column with many repeated values the estimate can be several times the real size (on 200,000 rows with 1,000 distinct values: 4,644,864 bytes estimated, 1,384,448 bytes real).
• The gateway truncates the query text it keeps to --query-metrics-sql-max-bytes (default 4096) without a marker. Plans and index advice use the full pg_stat_statements text or the full statement you give.
• get_top_queries shows the first 2,000 characters of each pg_stat_statements text and diagnose the first 500, with the full length and the queryid, so one very long statement cannot fill the 50,000-character result. The result says how to read a longer text with execute_sql in pieces of 20,000 characters. The lock check shows the first 500 characters of the waiting and blocking statements. The index advisors analyze the full text but list each skipped or costed query by its first 200 characters and full length, plus the queryid for workload queries, and show the first 500 characters of