postgresql

This PostgreSQL MCP server exposes a set of tools that allow Claude Code to interact with PostgreSQL databases in a read-only fashion. It supports listing databases, schemas, and tables, describing table structures, executing read-only queries, listing indexes with usage statistics, and retrieving execution plans and table statistics. All operations are designed with security in mind, defaulting to read-only access and using parameterized queries where applicable to mitigate injection risks. To begin using the server, configure the MCP connection in your Claude Code environment and point it to the PostgreSQL MCP executable via the provided environment variable POSTGRES_URL (or DATABASE_URL as an alternative). Once connected, you can invoke the available tools to explore your databases, understand table schemas, and run safe SELECT queries to retrieve data and insights.

Prerequisites:

• Go 1.25 or later
• Docker (recommended for running integration tests)
• Access to one or more PostgreSQL databases

Installation options:

Option 1: Build from source

git clone https://github.com/sgaunet/postgresql-mcp.git
cd postgresql-mcp
go build -o postgresql-mcp

Option 2: Download from GitHub Releases

1. Visit the releases page and download the appropriate binary for your platform (darwin, linux, windows).
2. Make it executable and place it in your PATH:

chmod +x postgresql-mcp_* 
sudo mv postgresql-mcp_* /usr/local/bin/postgresql-mcp

Option 3: Install via Homebrew (macOS/Linux)

brew tap sgaunet/homebrew-tools
brew install sgaunet/tools/postgresql-mcp

Option 4: Build and install for project usage

# Build
go build -o postgresql-mcp
# Install to PATH
sudo mv postgresql-mcp /usr/local/bin/

Configuration for a project (example):

{
  "mcpServers": {
    "postgres": {
      "type": "stdio",
      "command": "postgresql-mcp",
      "args": [],
      "env": {
        "POSTGRES_URL": "postgres://postgres:password@localhost:5432/postgres?sslmode=disable"
      }
    }
  }
}

Note: If you choose a different installation method, ensure the binary is accessible in your PATH and that the environment variable POSTGRES_URL (or DATABASE_URL) is properly configured before starting.

Environment variables and configuration tips:

• POSTGRES_URL (required): PostgreSQL connection string in the form postgres://user:password@host:port/dbname?sslmode=prefer
• DATABASE_URL (alternative): If POSTGRES_URL is not set, this will be used as a fallback.
• The server will attempt to connect on startup and will retry when the first tool is requested if the initial connection fails.

Common issues:

• Ensure PostgreSQL is reachable from the MCP runner and that firewall rules allow access.
• Confirm the user has read permissions for the databases/schemas/tables you intend to query.
• Remember that only SELECT and WITH queries are allowed for security.

Development and testing:

• Integration tests require Docker; use SKIP_INTEGRATION_TESTS=true to skip those tests during local runs if needed.
• The project depends on mcp-go, lib/pq, and testcontainers-go for testing.