Skip to main content
Glama
vallaksa

PostgreSQL MCP

by vallaksa
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

PostgreSQL MCP

Read-only Model Context Protocol server for PostgreSQL. Works with any MCP client — Cursor, Claude Desktop, Claude Code, VS Code, or custom clients over stdio or Streamable HTTP.

Database credentials stay on the server. Clients connect with a URL and API key (HTTP) or spawn the binary locally (stdio).

Features

  • query — read-only SQL (SELECT, WITH, EXPLAIN, SHOW) with row caps

  • list_tables — list tables in a schema

  • describe_table — column names, types, nullability, defaults

  • Resources — per-table schema JSON via MCP resources

  • Safety — SQL keyword guard + BEGIN READ ONLY transactions

  • Transports — stdio (local) and Streamable HTTP (hosted)

Related MCP server: db-mcp

Quick start

git clone https://github.com/vallaksa/postgresql-mcp.git
cd postgresql-mcp
npm install
npm run build

stdio (local MCP clients)

export DATABASE_URL="postgresql://mcp_reader:password@localhost:5432/devstrom"
npm start
# or: node dist/index.js

HTTP (hosted / remote MCP)

export DATABASE_URL="postgresql://mcp_reader:password@localhost:5432/devstrom"
export MCP_API_KEY="your-long-random-secret"
npm run start:http
# listens on http://0.0.0.0:3000/mcp

Client configuration

stdio — Claude Desktop, local Cursor, etc.

{
  "mcpServers": {
    "postgresql": {
      "command": "node",
      "args": ["/absolute/path/to/postgresql-mcp/dist/index.js"],
      "env": {
        "DATABASE_URL": "postgresql://mcp_reader:password@localhost:5432/devstrom"
      }
    }
  }
}

Or publish to npm:

{
  "mcpServers": {
    "postgresql": {
      "command": "npx",
      "args": ["-y", "postgresql-mcp"],
      "env": {
        "DATABASE_URL": "postgresql://mcp_reader:password@localhost:5432/devstrom"
      }
    }
  }
}

Streamable HTTP — any remote MCP client

Point the client at your hosted endpoint. No database URL in client config.

{
  "mcpServers": {
    "postgresql": {
      "url": "https://postgres-mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer your-api-key"
      }
    }
  }
}

Clients that only support stdio can bridge with mcp-remote:

{
  "mcpServers": {
    "postgresql": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://postgres-mcp.example.com/mcp",
        "--header",
        "Authorization:Bearer your-api-key"
      ]
    }
  }
}

Docker

Compose (homelab / shared Postgres network)

cp docker-compose.example.yml docker-compose.yml
cp .env.example .env   # set DATABASE_URL, MCP_API_KEY; encode @ in passwords as %40
docker compose up -d --build
curl -s http://127.0.0.1:3000/health

Expects an existing global-network and a Postgres container reachable as postgres (see comments in docker-compose.example.yml).

Single container

docker build -t postgresql-mcp .
docker run --rm -p 3000:3000 \
  -e DATABASE_URL="postgresql://mcp_reader:password@host.docker.internal:5432/devstrom" \
  -e MCP_API_KEY="your-api-key" \
  postgresql-mcp

Read-only database user

MCP_READER_PASSWORD='your-password' psql -U postgres -d devstrom \
  -v ON_ERROR_STOP=1 -f scripts/setup_readonly_user.sql

Environment variables

Variable

Description

DATABASE_URL

PostgreSQL connection string (server-side)

MCP_POSTGRES_URL

Alias for DATABASE_URL

MCP_TRANSPORT

stdio (default) or http

MCP_API_KEY

Bearer token for HTTP auth (required on non-loopback hosts)

HOST / MCP_HOST

HTTP bind address (default 0.0.0.0)

PORT / MCP_PORT

HTTP port (default 3000)

MCP_HTTP_PATH

HTTP MCP path (default /mcp)

MCP_MAX_ROWS

Max rows per query (default 100, max 1000)

CLI

postgresql-mcp              # stdio (default)
postgresql-mcp stdio        # stdio, explicit
postgresql-mcp http           # Streamable HTTP server
postgresql-mcp postgresql://...   # stdio with URL arg

Development

npm test
npm run typecheck
npm run dev -- postgresql://...
npm run dev:http

License

MIT

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityStale
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • mcp-postgres

    gbfeliped
    A
    license
    Not graded
    quality
    D
    maintenance
    Read-only PostgreSQL MCP server that enables running SELECT queries, listing tables and schemas, and describing columns, with built-in protection against writes and malicious SQL attacks.
    347 npm
    MIT

  • db-mcp

    eklemen
    A
    license
    A
    quality
    D
    maintenance
    Read-only PostgreSQL database MCP server for safely exploring schema, tables, relationships, and sample data without modification.
    10
    80 npm
    MIT

  • safe-postgres-mcp

    samuel-cabral
    A
    license
    Not graded
    quality
    B
    maintenance
    A zero-config, read-only PostgreSQL MCP server that enforces read-only access at the database level using READ ONLY transactions, allowing AI agents to safely explore schemas and run SELECT queries without risk of mutation.
    11 npm
    MIT

  • mcp-postgres

    imangali01
    F
    license
    Not graded
    quality
    B
    maintenance
    Read-only MCP server for PostgreSQL enabling schema introspection and SELECT queries via MCP clients like Claude, with multi-layered write protection.
    -