Catalog My learning Blog
Search courses and lessons
Training Hub Blog 5 min read
← All posts

The Postgres MCP Server You Find First Might Not Work

Title card: The Postgres MCP server you find first might not work, with the command uvx postgres-mcp resolving to version 0.1.0.

I was writing the Postgres guide for MCP Setup Guides, and I wanted every command in it to run. So I started a throwaway PostgreSQL 18 database, created a read-only user and ran the install command from the most popular Postgres MCP server's README.

It failed. Not with a clear error, but with this:

TEXT
Error connecting to database: invalid dsn: invalid connection option "--access-mode"

The server was treating its own flag as a database connection string. Here's what was going on, and which Postgres MCP server I'd use today.

Three servers, three very different states

Search for "Postgres MCP server" and three names come up. As of November 2026:

ServerState
@modelcontextprotocol/server-postgresThe original reference server. Its repository was archived in May 2025 and says it is no longer maintained, with no security guarantees.
Postgres MCP Pro (postgres-mcp)Good tuning tools, but the latest PyPI release (0.3.0, May 2025) can't be installed as documented.
DBHub (@bytebase/dbhub)Maintained by Bytebase, released this month, and worked first time.

Old tutorials still point at the first one, because for a while it was the obvious choice. It isn't any more.

What uvx did behind my back

Postgres MCP Pro's README says to run it with uvx postgres-mcp --access-mode=restricted. uvx installs a Python tool into a temporary environment and runs it. When I looked at what it had installed, it wasn't 0.3.0. It was 0.1.0.

Asking for 0.3.0 by name explained why:

TEXT
$ uvx postgres-mcp@0.3.0 --help
error: No solution found when resolving tool dependencies
  Because there is no version of pglast==7.2.0 and postgres-mcp>=0.3.0
  depends on pglast==7.2.0, we can conclude that postgres-mcp>=0.3.0
  cannot be used.

Version 0.3.0 pins an exact version of a dependency, pglast==7.2.0, that the resolver can no longer find. When you don't pin a version, uvx does the reasonable thing: it picks the newest release that *can* be installed. That's 0.1.0, which predates the --access-mode flag and expects a connection string as its only argument. So the flag became the "connection string", and the error made no sense.

Nothing about this is malicious or even unusual. It's what exact dependency pins do over time. But it means anyone following the README today gets an old version without being told, and the read-only "restricted" mode they asked for isn't there at all.

LessonPin the version of any MCP server you install, for example @bytebase/dbhub@1.6.0, and check which version actually runs. Floating installs can silently move backwards as well as forwards.

What I'd use instead

I switched the guide to DBHub. Against the same database it exposed two tools, execute_sql and search_objects, answered a count query, and connected through Gemini CLI once I raised the startup timeout to 30 seconds. It also supports MySQL, SQL Server, MariaDB, Oracle and SQLite, which is handy if you work across more than one database.

If you want Postgres MCP Pro for its index and health tools, its Docker image ships its own dependencies, so it sidesteps the PyPI problem.

The guard that doesn't depend on any of this

Whichever server you pick, connect it with a database role that can only read:

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;

When I asked DBHub to run delete from orders as this user, Postgres refused with "permission denied for table orders". A read-only flag in an MCP server is only as good as that server's code, and as this week showed, you might not even be running the version you think. A database permission holds no matter what.

The full setup, for Claude Code, Cursor, Codex and Gemini CLI, is in the Postgres MCP server guide.