mcp-postgres-server

A production-ready Model Context Protocol (MCP) server that gives AI assistants (Claude, etc.) direct, safe access to your PostgreSQL database.

What it does

mcp-postgres-server exposes five tools to any MCP-compatible client:

Quickstart

1. Install

pip install mcp-postgres-server

Or install from source:

git clone https://github.com/madmarin/mcp-postgres-server
cd mcp-postgres-server
pip install -e .

2. Configure

Copy .env.example to .env and fill in your connection details:

cp .env.example .env

Minimum required:

DATABASE_URL=postgresql+psycopg://user:password@localhost:5432/mydb

If your password contains special characters (for example @, :, /, #, %), URL-encode it in DATABASE_URL.

Example:

# Raw password: p@ss:w0rd/with#chars%
DATABASE_URL=postgresql+psycopg://postgres:p%40ss%3Aw0rd%2Fwith%23chars%25@localhost:5432/mydb

You can encode safely with Python:

python3 -c "import urllib.parse; print(urllib.parse.quote('p@ss:w0rd/with#chars%', safe=''))"

3. Run

mcp-postgres-server

The server starts in stdio mode by default, ready to be used by any MCP client.

Add to Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "postgres": {
      "command": "mcp-postgres-server",
      "env": {
        "DATABASE_URL": "postgresql+psycopg://user:password@localhost:5432/mydb"
      }
    }
  }
}

macOS note: Claude Desktop uses a restricted PATH and may not find the command by name. If you get a Server disconnected error, use the full path instead:

which mcp-postgres-server
# e.g. /Library/Frameworks/Python.framework/Versions/3.14/bin/mcp-postgres-server

Then use that full path as the "command" value in the config above.

Restart Claude Desktop — you will see the PostgreSQL tools available.

Add to Claude Code (CLI)

claude mcp add postgres -- mcp-postgres-server

Then set the environment variable:

export DATABASE_URL="postgresql+psycopg://user:password@localhost:5432/mydb"

Configuration Reference

All settings are read from environment variables or a .env file in the working directory.

Tool Reference

query(sql, params?)

Execute a read-only SELECT statement.

Input:
  sql     — SELECT statement or CTE
  params  — optional list of values for parameterized queries

Output (JSON):
  {
    "columns": ["id", "name", "age"],
    "rows": [[1, "Alice", 30], [2, "Bob", 25]],
    "row_count": 2,
    "execution_time_ms": 3.14
  }

Always use params for user-supplied values — never interpolate them into the SQL string.

# Safe
query("SELECT * FROM users WHERE name = %s", ["Alice"])

# Never do this
query(f"SELECT * FROM users WHERE name = '{user_input}'")

execute(sql, params?)

Run a write statement. Requires ALLOW_WRITE=true.

Output (JSON):
  {
    "rows_affected": 1,
    "status": "INSERT 0 1",
    "execution_time_ms": 2.5
  }

list_schemas()

Output (JSON):
  [
    {"schema_name": "public", "owner": "postgres"},
    {"schema_name": "analytics", "owner": "alice"}
  ]

list_tables(schema?)

Output (JSON):
  [
    {
      "table_name": "users",
      "table_type": "BASE TABLE",
      "row_estimate": 12345,
      "total_size": "2048 kB"
    }
  ]

describe_table(table, schema?)

Output (JSON):
  {
    "table": "users",
    "schema": "public",
    "columns": [
      {"name": "id", "type": "integer", "nullable": false, "default": "nextval(...)"},
      {"name": "name", "type": "text", "nullable": false, "default": null}
    ],
    "primary_key": ["id"],
    "foreign_keys": [],
    "indexes": [
      {"name": "users_pkey", "definition": "CREATE UNIQUE INDEX ..."}
    ]
  }

Security Model

• Read-only by default: the execute tool is disabled unless you explicitly set ALLOW_WRITE=true. This prevents accidental mutations.
• Parameterized queries: all tools use psycopg's parameterized query API. SQL is never built by string concatenation.
• Denylist: even with ALLOW_WRITE=true, certain destructive patterns (DROP DATABASE, ALTER SYSTEM, etc.) are blocked.
• Error isolation: internal error details (stack traces, SQL) are logged to stderr and never returned to the LLM.

Development

git clone https://github.com/madmarin/mcp-postgres-server
cd mcp-postgres-server
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev,test]"
pre-commit install

Run the tests (requires Docker for testcontainers):

pytest

Lint and format:

ruff check src tests
ruff format src tests
mypy src

See CONTRIBUTING.md for details on how to add new tools or submit a PR.

License

MIT