PostgreSQL — Claude Code MCP server: what it does, how to install
Connects AI assistants to PostgreSQL instances locally or in cloud providers like Neon and RDS. Inspect table schemas and run read-only queries from chat.
claude mcp add --env DATABASE_URL=<DATABASE_URL> --env PG_HOST=<PG_HOST> --env PG_PORT=<PG_PORT> --env PG_USER=<PG_USER> --env PG_PASSWORD=<PG_PASSWORD> --transport stdio postgresql -- npx -y mcp-postgres-serverWhat PostgreSQL does
The server runs via npx over stdio and needs Node.js 20 or newer. It keeps dependencies minimal, relying on pg, zod, and pg-connection-string. A single DATABASE_URL is enough for setup, though discrete host and port variables are also supported.
Safety is the default. In read-only mode, queries run inside a BEGIN READ ONLY block followed by ROLLBACK, guaranteeing that writes cannot slip through. The agent inspects schemas and fetches column details with tools like describe_table and list_tables.
Write operations stay blocked. Unless PG_ALLOW_WRITE is explicitly set to true, the execute tool refuses to run any mutating statements.
What it helps with
- inspect database tables and column types
- run read-only SQL queries with bound parameters
- connect your coding agent to Neon or Docker databases
- safely explore production schemas without accidental writes
Example prompts for the agent
- List all available tables in the
publicschema. - Describe the structure and columns of the
userstable. - Run
SELECT id, name FROM users WHERE email = $1with parameter[email protected].
How to install PostgreSQL
Platform CLI
claude mcp add --env DATABASE_URL=<DATABASE_URL> --env PG_HOST=<PG_HOST> --env PG_PORT=<PG_PORT> --env PG_USER=<PG_USER> --env PG_PASSWORD=<PG_PASSWORD> --transport stdio postgresql -- npx -y mcp-postgres-serverReplace <…> with your own values. 17 more environment variables are in the server README
Platform CLI
codex mcp add postgresql --env DATABASE_URL=<DATABASE_URL> --env PG_HOST=<PG_HOST> --env PG_PORT=<PG_PORT> --env PG_USER=<PG_USER> --env PG_PASSWORD=<PG_PASSWORD> -- npx -y mcp-postgres-serverReplace <…> with your own values. 17 more environment variables are in the server README
Config file
{
"mcpServers": {
"postgresql": {
"command": "npx",
"args": [
"-y",
"mcp-postgres-server"
],
"env": {
"DATABASE_URL": "<DATABASE_URL>",
"PG_HOST": "<PG_HOST>",
"PG_PORT": "<PG_PORT>",
"PG_USER": "<PG_USER>",
"PG_PASSWORD": "<PG_PASSWORD>"
}
}
}
}Replace <…> with your own values. 17 more environment variables are in the server README
Config file
{
"servers": {
"postgresql": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"mcp-postgres-server"
],
"env": {
"DATABASE_URL": "<DATABASE_URL>",
"PG_HOST": "<PG_HOST>",
"PG_PORT": "<PG_PORT>",
"PG_USER": "<PG_USER>",
"PG_PASSWORD": "<PG_PASSWORD>"
}
}
}
}Replace <…> with your own values. 17 more environment variables are in the server README
Platform CLI
gemini mcp add -e DATABASE_URL=<DATABASE_URL> -e PG_HOST=<PG_HOST> -e PG_PORT=<PG_PORT> -e PG_USER=<PG_USER> -e PG_PASSWORD=<PG_PASSWORD> postgresql npx -y mcp-postgres-serverReplace <…> with your own values. 17 more environment variables are in the server README
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about PostgreSQL
How to install PostgreSQL in Claude Code?
Run `claude mcp add --env DATABASE_URL=<DATABASE_URL> --env PG_HOST=<PG_HOST> --env PG_PORT=<PG_PORT> --env PG_USER=<PG_USER> --env PG_PASSWORD=<PG_PASSWORD> --transport stdio postgresql -- npx -y mcp-postgres-server` in your terminal.
What does the PostgreSQL MCP server do?
It lets MCP clients inspect database schemas, read table structures, and run parameterized SQL statements over stdio.
Can the model modify database records?
Not by default. Writes are forbidden and rejected until you enable PG_ALLOW_WRITE="true" in the environment.
