Postgres MCP Server Setup with DBHub (Read-Only)
On this page
Which Postgres server should you use?
Search for "Postgres MCP server" and you'll find three names. As of November 2026 they're in very different states:
| Server | Status | Use it? |
|---|---|---|
@modelcontextprotocol/server-postgres | Archived in May 2025, "no longer maintained", with no security guarantees | No |
Postgres MCP Pro (postgres-mcp) | Useful tuning tools, but its PyPI package hasn't had a release since May 2025 and the latest version won't install (see below) | Only through its Docker image |
DBHub (@bytebase/dbhub) | Maintained by Bytebase, with a release in November 2026. Supports Postgres, MySQL, SQL Server, MariaDB, Oracle and SQLite | Yes, as the default |
This guide uses DBHub. Everything below was run against DBHub 1.6.0 and a local PostgreSQL 18.
Step 1: create a read-only database role
Do this first. The strongest guard against an agent changing data isn't a setting in the MCP server, it's a database user that isn't allowed to. Postgres enforces it no matter what the agent asks for.
CREATE ROLE mcp_readonly LOGIN PASSWORD 'choose-a-strong-password';
GRANT CONNECT ON DATABASE shop TO mcp_readonly;
GRANT USAGE ON SCHEMA public TO mcp_readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO mcp_readonly;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO mcp_readonly;The last line makes sure tables you create later are readable too. Put the connection string in an environment variable:
export SHOP_DB_DSN='postgres://mcp_readonly:choose-a-strong-password@localhost:5432/shop?sslmode=disable'Use sslmode=require for any database that isn't on your own machine.
Step 2: add DBHub to your tool
DBHub needs Node.js 22.5 or newer. Pass the connection string with --dsn.
Claude Code (project scope with the variable, so the file holds no password):
{
"mcpServers": {
"shop-db": {
"command": "npx",
"args": ["-y", "@bytebase/dbhub@1.6.0", "--dsn", "${SHOP_DB_DSN}"]
}
}
}Save that as .mcp.json in your repository. Claude Code expands ${SHOP_DB_DSN} from each developer's environment.
Cursor uses the same shape in .cursor/mcp.json, with ${env:SHOP_DB_DSN} as the variable syntax.
Codex CLI:
codex mcp add shop-db -- npx -y @bytebase/dbhub@1.6.0 --dsn "$SHOP_DB_DSN"Here your shell fills in the variable when you run the command, so the full connection string, password included, is saved in ~/.codex/config.toml. Keep that in mind on shared machines.
Gemini CLI:
gemini mcp add -s user --timeout 30000 shop-db npx -y @bytebase/dbhub@1.6.0 --dsn '$SHOP_DB_DSN'The --timeout matters. In testing, Gemini CLI 0.67 reported DBHub as Disconnected with the default timeout and Connected with 30 seconds. Also note that gemini mcp list prints the expanded connection string, password included, so don't run it while sharing your screen.
Step 3: see what the agent can do
By default DBHub exposes two tools:
execute_sqlruns a query and returns the rows as JSON.search_objectsfinds tables, columns and other objects, so the agent can learn your schema before writing SQL.
Two more, explain_sql and health_check, are opt-in. You can also define your own named tools in a dbhub.toml file, which is a neat way to give the agent a safe, fixed query instead of free-form SQL.
Here's what happened when DBHub was asked to run a query, then a delete, as the read-only role:
execute_sql "select count(*) as n from orders" -> {"n": "1000"}
execute_sql "delete from orders" -> isError: true, "permission denied for table orders"The delete fails inside Postgres, so it doesn't matter how the request was phrased.
What about Postgres MCP Pro?
Postgres MCP Pro adds tuning tools that DBHub doesn't have, such as analyze_db_health, get_top_queries and analyze_workload_indexes. Its README suggests installing with uvx postgres-mcp. In November 2026 that doesn't work as written. Version 0.3.0 depends on pglast==7.2.0, which is no longer available, so uvx quietly falls back to version 0.1.0. That old version doesn't understand --access-mode and treats it as a broken connection string.
If you want its tuning tools, use the Docker image, which ships its own dependencies, and keep the read-only role from Step 1:
{
"mcpServers": {
"postgres": {
"command": "docker",
"args": ["run", "-i", "--rm", "-e", "DATABASE_URI", "crystaldba/postgres-mcp", "--access-mode=restricted"],
"env": { "DATABASE_URI": "postgresql://mcp_readonly:password@host.docker.internal:5432/shop" }
}
}
}Inside the container, localhost is the container itself, so host.docker.internal is used to reach a database on your machine. Its index tools also need the pg_stat_statements and hypopg extensions in your database.
Check yourself
Postgres enforces the role's permissions on every query, whatever the server or agent does. A flag in the server is only as good as that server's code.
uvx installed the old 0.1.0 release because 0.3.0's dependencies can't be resolved. That version doesn't support --access-mode. Use DBHub or the Docker image.
Commit a project config that references an environment variable, such as ${SHOP_DB_DSN} in Claude Code's .mcp.json, and have each person set the variable locally.