Package Exports

@calebmabry/postgres-mcp-server
@calebmabry/postgres-mcp-server/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@calebmabry/postgres-mcp-server) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Postgres MCP Server

A Model Context Protocol (MCP) server that provides secure database access to PostgreSQL through Kysely ORM. This server enables Claude Desktop to interact with PostgreSQL databases using natural language.

📚 Documentation

Full documentation is available at: caleb-mabry.github.io/postgres-mcp

Quick Links

Features

MCP Tools: Query execution, table listing, schema inspection, and constraint information
Type Safety: Full TypeScript support with typed inputs/outputs
Connection Pooling: Configurable connection limits with idle timeout
Error Handling: Graceful error messages for connection and query issues
Security: Parameterized queries to prevent SQL injection

Quick Start

For Claude Desktop Users

See the 📖 Claude Desktop Setup Guide for complete instructions.

For HTTP/API Usage

See the 📖 HTTP Server Setup Guide for complete instructions.

For Docker

See the 📖 Docker Setup Guide for complete instructions.

Direct Installation

npx -y @calebmabry/postgres-mcp-server

Configuration

Create a .env file with your database credentials:

DB_HOST=127.0.0.1
DB_PORT=5432
DB_USER=postgres
DB_PASSWORD=your_password_here
DB_NAME=postgres
DB_SSL=true

# HTTP Server mode only (optional)
PORT=3000
ALLOWED_HOSTS=localhost,127.0.0.1

Available Tools

Tool	Description	Required Parameters	Optional Parameters
`query`	Execute SQL queries with pagination support	`sql` (string)	`pageSize` (1-500), `offset` (number), `parameters` (array)
`describe_table`	Get table structure and column details	`schema` (string), `table` (string)	-
`list_tables`	List all tables in a schema	`schema` (string)	-
`list_schemas`	List all schemas in the database	-	`includeSystemSchemas` (boolean)
`get_constraints`	Get table constraints (PK, FK, etc.)	`schema` (string), `table` (string)	-
`list_indexes`	List indexes for a table or schema	`schema` (string)	`table` (string)
`list_views`	List views in a schema	`schema` (string)	-
`list_functions`	List functions and procedures	`schema` (string)	-
`explain_query`	Get query execution plan	`sql` (string)	`analyze` (boolean), `format` (text/json/xml/yaml)
`get_table_stats`	Get table size and statistics	`schema` (string)	`table` (string)

Key Features

Pagination: Query tool supports up to 500 rows per page with automatic LIMIT/OFFSET handling
Security: Parameterized queries prevent SQL injection, READ_ONLY mode by default
Type Safety: Full TypeScript support with Zod schema validation

Client Configuration

The postgres-mcp-server works with any MCP-compatible client. See configuration examples below:

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "postgres-mcp-server": {
      "command": "npx",
      "args": ["-y", "@calebmabry/postgres-mcp-server"],
      "env": {
        "DB_HOST": "127.0.0.1",
        "DB_PORT": "5432",
        "DB_USER": "postgres",
        "DB_PASSWORD": "your_password_here",
        "DB_NAME": "your_database_name",
        "DB_SSL": "false",
        "READ_ONLY": "true"
      }
    }
  }
}

Config locations:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

See claude_config_example.json for a full example.

Cline (VS Code)

Add to .cline/mcp_settings.json:

{
  "mcpServers": {
    "postgres-mcp-server": {
      "command": "npx",
      "args": ["-y", "@calebmabry/postgres-mcp-server"],
      "env": {
        "DB_HOST": "localhost",
        "DB_NAME": "your_database",
        "DB_USER": "postgres",
        "DB_PASSWORD": "your_password"
      }
    }
  }
}

See cline_mcp_settings_example.json for a full example.

Zed Editor

Add to Zed settings (Settings → Context Servers):

{
  "context_servers": {
    "postgres-mcp-server": {
      "command": {
        "path": "npx",
        "args": ["-y", "@calebmabry/postgres-mcp-server"]
      },
      "settings": {
        "DB_HOST": "localhost",
        "DB_NAME": "your_database",
        "DB_USER": "postgres",
        "DB_PASSWORD": "your_password"
      }
    }
  }
}

See zed_settings_example.json for a full example.

Docker

Use the included Dockerfile or docker-compose.yml:

docker-compose up -d

See docker-compose.example.yml for a full example.

Development

# Clone and install dependencies
git clone https://github.com/caleb-mabry/postgres-mcp.git
cd postgres-mcp-server
npm install

# Run in development mode with hot reload
npm run dev

# Build for production
npm run build

# Run tests
npm run test

# Run specific test suites
npm run test:unit
npm run test:integration

Environment Variables

Variable	Default	Description
`DB_HOST`	`127.0.0.1`	PostgreSQL host
`DB_PORT`	`5432`	PostgreSQL port
`DB_USER`	`postgres`	Database user
`DB_PASSWORD`	required	Database password
`DB_NAME`	`postgres`	Database name
`DB_SSL`	`false`	Enable SSL connection (set to `false` for local dev)
`READ_ONLY`	`true`	Restrict to SELECT/WITH/EXPLAIN queries
`QUERY_TIMEOUT`	`30000`	Query timeout in milliseconds
`MAX_PAGE_SIZE`	`500`	Maximum rows per page
`DEFAULT_PAGE_SIZE`	`100`	Default page size when not specified
`PORT`	`3000`	HTTP server port (HTTP mode only)
`ALLOWED_HOSTS`	none	Comma-separated allowed hosts (HTTP mode only). Example: `localhost,127.0.0.1,example.com`
`MODE`	`stdio`	Server mode in Docker: `stdio` or `http`

For detailed documentation on all features and setup options, visit caleb-mabry.github.io/postgres-mcp.

License

ISC