pg

This MCP server provides a controlled interface to a PostgreSQL database, allowing large language models and tools to query and analyze data safely. It exposes a SQL-oriented communication surface through a configurable transport (stdio by default; can also run over HTTP). The primary tool exposed is a query capability that can execute SQL statements against the connected Postgres database, returning results in a structured format for downstream processing. You can also request schema and sample data for tables via the built-in resources endpoints. Start with the stdio transport for local usage or switch to HTTP to enable streaming interactions with compatible clients.

To use, configure your MCP client to connect to the postgres server block (named postgres in the config). The client passes SQL commands via the query tool, for example by sending a JSON payload such as { "sql": "SELECT * FROM users WHERE active = true LIMIT 10" }. You can also ask for listing tables and their schemas through the provided resources, e.g. postgres://tables for a list of tables or postgres://table/{schema}/{table} for a specific table’s schema and sample data.

The server supports a few environment-driven controls: enable or disable write operations with DANGEROUSLY_ALLOW_WRITE_OPS, toggle debug logs with DEBUG, and optionally supply a TLS root certificate via PG_SSL_ROOT_CERT when connecting to TLS-enabled databases. When using the HTTP transport, you can connect clients to the MCP Streamable HTTP endpoint at /mcp on port 3000 by default.

Prerequisites:

• Node.js (LTS) or Bun (as shown in the repository) or a compatible runtime that can run npx and node.
• A running PostgreSQL database accessible via a connection string.
• Optional: Docker if you prefer containerized usage.

Installation steps:

1. Install dependencies and set up the project (example for a local clone):

# If starting from a repository clone
git clone https://github.com/ericzakariasson/pg-mcp-server.git
cd pg-mcp-server
bun install

2. Build or install the MCP server package as needed (examples shown in the repo):

# For a local development run (stdio transport)
bun run index.ts -- --transport=stdio
# For HTTP transport
bun run index.ts -- --transport=http

3. Start the server with your preferred transport and environment variables:

# Example using stdio transport with a PostgreSQL URL set
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/postgres" bun run index.ts -- --transport=stdio

# Example using HTTP transport
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/postgres" bun run index.ts -- --transport=http

4. Optional: run via npx as suggested in the README configuration snippet:

npx --yes pg-mcp-server --transport stdio

5. If you use Docker, you can adapt the commands to containerized workflows (not shown here in detail).

Tips and caveats:

• Ensure DATABASE_URL is correctly set and points to your Postgres instance. The server relies on this connection string for all queries.
• If you enable DANGEROUSLY_ALLOW_WRITE_OPS, be mindful of the potential for unintended data modification.
• The default transport is stdio; HTTP mode exposes a streamable HTTP endpoint at /mcp (port 3000 by default). Use appropriate security controls when exposing HTTP.
• PG_SSL_ROOT_CERT can be provided if your database requires TLS with a custom CA bundle (e.g., AWS RDS CA).
• When developing locally, you can use the provided sample data (e.g., users, products, orders) to test queries and table schemas.
• For debugging, set DEBUG=true to enable verbose logs during development.