Install Postgres MCP in Claude Code (2026 Guide)
A. Frans
Published June 13, 2026
Table of Contents
Once the Postgres MCP server is wired into Claude Code, you stop writing SQL by hand for the boring stuff. You type "show me the 10 most recent signups who never placed an order" and Claude inspects your schema, writes the join, runs it, and hands back rows. No switching to psql, no remembering whether the column is created_at or signup_date. The model reads the actual table structure and works from there.
This guide gets you from nothing to a working connection in about ten minutes, with the safety rails that keep an over-eager model from running DELETE against production.
What you need first
Three things before you start:
- Claude Code installed and working. Open a terminal, run
claude --version. If that prints a version number, you're set. If not, install it from Anthropic's docs and sign in once. - Node.js 18 or newer. Run
node --version. The MCP server runs throughnpx, which ships with Node. Anything 18+ is fine. - A Postgres connection string you can reach. Something like
postgresql://user:password@host:5432/dbname. Local, a Docker container, RDS, Supabase, Neon, doesn't matter, as long as the machine running Claude Code can open a TCP connection to it.
Test the connection string before you hand it to Claude. If you have psql around:
psql "postgresql://user:password@localhost:5432/mydb" -c "SELECT 1;"
If that returns a 1, the credentials and network path are good. Half the "MCP won't connect" problems are just a bad connection string, and it's faster to catch that here than through the model.
Install it: the CLI way
The fastest path is claude mcp add. From any terminal:
claude mcp add postgres -- npx -y @modelcontextprotocol/server-postgres postgresql://USER:PASS@HOST:5432/DBNAME
Breaking that down so you know what each piece does:
claude mcp add postgres— registers a server under the namepostgres. That name is what shows up later when you run/mcp.--— separates Claude's own flags from the command it should run. Everything after this is the server's launch command.npx -y @modelcontextprotocol/server-postgres— downloads and runs the Postgres MCP server package. The-yskips the install prompt so it doesn't hang waiting for input.postgresql://USER:PASS@HOST:5432/DBNAME— your connection string, passed as the server's one argument.
A package note worth your attention: @modelcontextprotocol/server-postgres was the original reference server, and the ecosystem has churned. Some teams have moved to community-maintained packages like @crystaldba/postgres-mcp (often called Postgres MCP Pro) that add query plans and read-only enforcement. Before you commit, run npm view @modelcontextprotocol/server-postgres to confirm the package still publishes, and check which one the current MCP server directory points to. If the reference package is deprecated by the time you read this, swap the package name in the command above, the rest of the shape stays identical.
By default claude mcp add registers the server at local scope, meaning it's available only to you in the current project. If you want it shared across every project on your machine, add -s user. If you want it committed to the repo for your whole team, use -s project (which writes to .mcp.json, more on that next).
Install it: the manual config way
Sometimes you'd rather see the config than type a long command, or you want the server checked into the repo so teammates get it automatically. That's the .mcp.json file, placed at the root of your project:
{
"mcpServers": {
"postgres": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-postgres",
"postgresql://USER:PASS@HOST:5432/DBNAME"
]
}
}
}
command is the executable Claude Code spawns. args is the list of arguments handed to it, in order, same pieces as the CLI version, just structured. The key under mcpServers (postgres here) is the display name.
Don't put a raw password in a file you commit. Pull it from an environment variable instead:
{
"mcpServers": {
"postgres": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-postgres",
"postgresql://readonly:${POSTGRES_PASSWORD}@db.internal:5432/app"
],
"env": {
"POSTGRES_PASSWORD": "${POSTGRES_PASSWORD}"
}
}
}
}
Now the secret lives in your shell or a .env you've gitignored, and .mcp.json is safe to share. Set it in your shell before launching Claude Code:
export POSTGRES_PASSWORD='your-real-password'
After editing .mcp.json, restart Claude Code so it picks up the change. If you added the server at project scope and a teammate pulls it down, Claude Code asks them to approve the server before it runs, that approval prompt is a feature, not a bug. It stops a malicious config in a repo from auto-executing on someone's machine.
Confirm it actually connected
Inside Claude Code, type:
/mcp
You'll get a list of registered MCP servers and their status. postgres should show as connected. If it says failed or shows a spinner that never resolves, the server started but couldn't reach the database, jump to troubleshooting below.
A connected server isn't proof the credentials work, only that the process launched. Make Claude actually touch the database to be sure:
What tables exist in this database?
If it comes back with your real table names, you're done. The model queried the schema and got rows. That's the whole loop working.
What you can ask it
This is where it earns its keep. A few prompts that show the range:
- "Describe the
orderstable, columns, types, and which ones are indexed." - "How many users signed up each month this year? Give me a count per month."
- "Find any orders with a NULL
customer_idand tell me how many there are." - "What's the average time between a user's signup and their first order?"
- "Show me the schema for every table that references
products."
Claude reads the schema, writes the SQL, runs it, and explains the result. When a query is slow or a join looks off, you can ask it to show the query it ran and tweak from there. It's a real back-and-forth, not a one-shot.
Make it read-only (do this)
The single most important step. By default the model can run whatever SQL it writes, and a misread prompt can turn "clean up old test rows" into a DELETE against live data. Don't rely on the model behaving. Take the permission away at the database level.
Create a Postgres role that physically cannot write, and point your connection string at that role:
-- Connect as a superuser, then:
CREATE ROLE claude_readonly WITH LOGIN PASSWORD 'a-strong-password';
GRANT CONNECT ON DATABASE myapp TO claude_readonly;
GRANT USAGE ON SCHEMA public TO claude_readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO claude_readonly;
-- So new tables are readable too, without redoing the grant:
ALTER DEFAULT PRIVILEGES IN SCHEMA public
GRANT SELECT ON TABLES TO claude_readonly;
Now build your connection string with claude_readonly instead of an admin user:
postgresql://claude_readonly:a-strong-password@host:5432/myapp
With those grants, an INSERT, UPDATE, or DROP fails with a permission error no matter what the model tries. You get all the read power and none of the blast radius. If you genuinely need writes later, make a second server entry with a write-capable role and only enable it when you mean it.
When it won't connect
/mcp shows the server as failed. First check the logs. Run claude mcp list to see what's registered, then launch with claude --debug to watch the server's startup output. Most failures print a clear Postgres error there.
password authentication failed for user. The credentials are wrong or the role can't log in. Re-test with psql using the exact same connection string. Watch for special characters in the password, a @, #, or / in the password breaks URL parsing. URL-encode them: @ becomes %40, # becomes %23.
connection refused. Nothing is listening at that host and port. Confirm Postgres is running (pg_isready -h host -p 5432), confirm the port is right, and confirm Postgres accepts TCP connections, listen_addresses in postgresql.conf has to include the interface you're hitting, not just localhost if you're connecting remotely.
SSL errors like no encryption or server does not support SSL. Managed providers (RDS, Supabase, Neon) usually require SSL; a bare local instance usually doesn't. Append the right mode to the connection string. For a provider that requires it: ...?sslmode=require. For a local box that doesn't speak SSL and is throwing an error: ...?sslmode=disable. If a provider needs certificate verification, sslmode=verify-full plus the CA path is the stricter option.
It connects but sees no tables. The role lacks USAGE on the schema, or your tables live in a schema other than public. Grant USAGE on the right schema, or qualify it in your prompt ("look in the analytics schema").
Two retries and still stuck? Drop the server and re-add it clean: claude mcp remove postgres, then run the add command again. A stale registration from a half-finished earlier attempt is a common culprit.
Keep the credentials safe
A few habits that save you a bad afternoon:
Never commit a connection string with a live password. Add .env to .gitignore before you write the password into it, and keep secrets out of .mcp.json by using the ${VAR} env-substitution shown above. If you ever do paste a real password into a committed file, rotate it, it's in your git history forever once pushed, and history rewrites rarely catch every clone.
Give Claude the least access that does the job. The read-only role above is the floor. If the work only touches three tables, grant SELECT on those three, not the whole schema. Scope the server to local unless your team genuinely needs it shared, so a shared config doesn't quietly hand someone's laptop a path to your production database.
If you're connecting to anything beyond your own laptop, treat the connection string like a production secret, because it is one. Anyone who can read it can read your data.
For the next steps, the same pattern covers other backends, see how to install the Supabase MCP server in Claude Code if your Postgres lives behind Supabase, and the GitHub MCP setup guide to give Claude your repos too. If you're still deciding whether you even want an MCP server versus a lighter-weight extension, the difference between MCP servers and agent skills lays out when each one fits.
FAQ
Does the Postgres MCP server work with any Postgres, or only managed ones? Any Postgres that speaks the standard wire protocol. Local installs, Docker containers, RDS, Supabase, Neon, Cloud SQL, they all use the same postgresql:// connection string. The only thing that varies is whether SSL is required, which you handle with the sslmode parameter.
Can Claude modify my data, or only read it? That's up to your database role, not the model. If you connect with an admin user, Claude can run any SQL it writes, including writes and deletes. If you connect with the read-only role from this guide, writes fail at the database level. Use read-only unless you have a specific reason not to.
Where does Claude Code store the MCP config? Local-scope servers live in your project's local Claude Code settings; project-scope servers go in .mcp.json at the repo root (meant to be committed); user-scope servers apply across all your projects. Run claude mcp list to see what's registered and at which scope.
The package name in the command looks different from what I see online. Which is right? The MCP ecosystem moves fast and package ownership has shifted. Run npm view <package-name> to confirm a package is still published, and check the current MCP server directory for the recommended Postgres server. The command structure stays the same, only the package name after npx -y changes.
Do I need to restart Claude Code after editing .mcp.json? Yes. Claude Code reads MCP config at startup. After any edit to .mcp.json or a claude mcp add/remove, restart the session, then run /mcp to confirm the server reconnected.
Share this article
📄Related Articles
Get More AI Tool Guides
New comparisons and guides every week. Join thousands of professionals staying ahead of the AI curve.