Catalog My learning Blog
MCP Setup Guides: Cursor, Codex, Gemini CLI and Top Servers · Phase 2 · Lesson 10 · 4 min read

Postgres MCP Server Setup with DBHub (Read-Only)

On this page
  1. Which Postgres server should you use?
  2. Step 1: create a read-only database role
  3. Step 2: add DBHub to your tool
  4. Step 3: see what the agent can do
  5. What about Postgres MCP Pro?
  6. Check yourself

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:

ServerStatusUse it?
@modelcontextprotocol/server-postgresArchived in May 2025, "no longer maintained", with no security guaranteesNo
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 SQLiteYes, 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.

SQL
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:

Shell
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):

JSON
{
  "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:

Code
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:

Code
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_sql runs a query and returns the rows as JSON.
  • search_objects finds 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:

SQL
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:

JSON
{
  "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.