home / mcp / postgres mcp server

Postgres MCP Server

Provides a read-only PostgreSQL query API via MCP with validation and a 10s timeout.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "rathoddarshil-mcp-postgres-query-server": {
      "command": "node",
      "args": [
        "/path/to/your/mcp-postgres-query-server/dist/index.js",
        "postgresql://username:password@hostname:5432/database"
      ]
    }
  }
}

You can run a read-only MCP server that lets clients query a PostgreSQL database securely and efficiently. It validates queries to ensure only SELECT statements run, enforces a 10-second timeout, and formats results as JSON for easy consumption by MCP clients like Claude Desktop.

How to use

Use your MCP client to connect to the PostgreSQL query server you run locally or on a server. The server exposes a read-only interface to your database and returns query results in JSON. You will typically configure your MCP client to use the stdio-based MCP server that you start from the project, passing the PostgreSQL connection string as an argument. Once connected, you can send SELECT queries to retrieve data from your database. The server will validate that each query is read-only and will terminate any query that runs longer than the allowed timeout.

How to install

Prerequisites you need before installing the MCP server:

Node.js (v14 or later) with npm
PostgreSQL database (connection details available to you)

Install and run the server with these steps:

# Clone the repository
git clone https://github.com/RathodDarshil/mcp-postgres-query-server.git
cd mcp-postgres-query-server

# Install dependencies
npm install

# Build the project
npm run build

Configure Claude Desktop to connect automatically

Configure Claude Desktop to automatically launch and connect to the MCP server by editing the application configuration and adding the server entry under mcpServers.

{
  "mcpServers": {
    "postgres-query": {
      "command": "node",
      "args": [
        "/path/to/your/mcp-postgres-query-server/dist/index.js",
        "postgresql://username:password@hostname:port/database"
      ]
    }
  }
}

Updating configuration

To apply changes to the client configuration, open Claude Desktop, adjust the config file as needed, save, and restart Claude Desktop for the changes to take effect. If you updated the MCP server code, rebuild it before restarting Claude Desktop.

Additional notes

Security and operation details to keep in mind include that all queries are validated to be read-only, the database connection can be configured to use SSL, and the server enforces a 10-second timeout to prevent resource exhaustion.

Configuration at a glance

The MCP server is started using a stdio configuration with node and the built index script, together with a PostgreSQL connection string. The example shows how to pass the connection string as an argument to the server executable.

Security considerations

- All queries are validated to ensure they are read-only. - The server uses the provided database connection with SSL where available. - A timeout protects against long-running queries. - No write operations are permitted. - Credentials are provided via the connection string and are not stored in files.

Development

Key components live in the server source and include a PostgreSQL connection pool, query validation logic, the MCP server configuration, and tool/resource definitions. To adjust behavior, you can modify the read-only query checks and timeout duration.

Available tools

query-postgres

Executes a read-only SQL query against the configured PostgreSQL database.