What can you do with this server?

This server provides a secure, comprehensive interface for PostgreSQL database interaction through MCP-compatible clients like Claude and Cursor, offering query execution, schema exploration, performance analysis, and guided workflows. **Query & Execution**: Run read-only SQL queries (`SELECT`) with automatic safety validation, or enable write operations (`INSERT/UPDATE/DELETE`) via `ALLOW_WRITE_OPERATIONS=true`. Analyze query performance with `EXPLAIN` and `EXPLAIN ANALYZE` plans. **Schema Discovery**: Browse and inspect database structures using `list_schemas`, `list_tables`, `describe_table`, `list_views`, `describe_view`, and `list_functions` to explore schemas, tables, views, columns, data types, constraints, and procedures. **Performance Analysis**: Optimize queries and analyze database health with `table_stats` (row counts, disk size, bloat metrics), `list_indexes` (columns, types, sizes), and `list_constraints` (primary keys, foreign keys, unique, check constraints). **Database Information**: Retrieve metadata via `get_database_info` (version, connection details, settings) and search for columns across tables with `search_columns`. **Security Features**: Default read-only mode, SQL injection prevention with query validation, credential protection, and configurable limits (`MAX_ROWS` default 1000, `QUERY_TIMEOUT` default 30s). **Guided Workflows**: Access MCP prompts for assisted tasks: `explore_database`, `query_builder`, `performance_analysis`, and `data_dictionary` generation. **Resource Browsing**: Navigate database structure as markdown through MCP resources (e.g., `postgres://schemas`, `postgres://schemas/{schema}/tables`). **Cross-Platform Support**: Available in TypeScript (recommended for Smithery) and Python versions with identical functionality, compatible with Claude Code, Claude Desktop, and Cursor IDE.

Which integrations are available for this server?

Enables comprehensive [PostgreSQL](/mcp/servers/integrations/postgresql) database operations including query execution, schema exploration, table analysis, performance optimization with EXPLAIN plans, and browsable database structure as MCP resources. Provides read-only access by default with optional write operations, SQL injection prevention, and tools for searching columns, analyzing statistics, and generating data dictionaries.

PostgreSQL MCP Server

PyPI version npm version License: MIT

MCP server for PostgreSQL database operations. Works with Claude Code, Claude Desktop, Cursor, and any MCP-compatible client.

Language Versions

This repository contains both TypeScript and Python implementations:

Version	Directory	Status	Installation
TypeScript	`/typescript`	✅ Recommended (Smithery)	`npm install -g postgresql-mcp`
Python	`/python`	✅ Stable	`pipx install postgresql-mcp`

Note: The TypeScript version is used for Smithery deployments. Both versions provide identical functionality.

Features

Query Execution: Execute SQL queries with read-only protection by default
Schema Exploration: List schemas, tables, views, and functions
Table Analysis: Describe structure, indexes, constraints, and statistics
Performance Tools: EXPLAIN queries and analyze table health
Security First: SQL injection prevention, credential protection, read-only by default
MCP Prompts: Guided workflows for exploration, query building, and documentation
MCP Resources: Browsable database structure as markdown

Quick Start

TypeScript (Recommended for Smithery)

# Install globally npm install -g postgresql-mcp # Or run directly with npx npx postgresql-mcp

Python

# Install pipx install postgresql-mcp # Configure Claude Code claude mcp add postgres -s user \ -e POSTGRES_HOST=localhost \ -e POSTGRES_USER=your_user \ -e POSTGRES_PASSWORD=your_password \ -e POSTGRES_DB=your_database \ -- postgresql-mcp

Full Installation Guide - Includes database permissions setup, remote connections, and troubleshooting.

Configuration

Environment Variables

Variable	Required	Default	Description
`POSTGRES_HOST`		localhost	Database host
`POSTGRES_PORT`		5432	Database port
`POSTGRES_USER`	✅		Database user
`POSTGRES_PASSWORD`	✅		Database password
`POSTGRES_DB`	✅		Database name
`POSTGRES_SSLMODE`		prefer	SSL mode
`ALLOW_WRITE_OPERATIONS`		false	Enable INSERT/UPDATE/DELETE
`QUERY_TIMEOUT`		30	Query timeout (seconds)
`MAX_ROWS`		1000	Maximum rows returned

Claude Code CLI

# TypeScript version claude mcp add postgres -s user \ -e POSTGRES_HOST=localhost \ -e POSTGRES_USER=your_user \ -e POSTGRES_PASSWORD=your_password \ -e POSTGRES_DB=your_database \ -- npx postgresql-mcp # Python version claude mcp add postgres -s user \ -e POSTGRES_HOST=localhost \ -e POSTGRES_USER=your_user \ -e POSTGRES_PASSWORD=your_password \ -e POSTGRES_DB=your_database \ -- postgresql-mcp

Cursor IDE

Add to ~/.cursor/mcp.json:

{ "mcpServers": { "postgres": { "command": "npx", "args": ["postgresql-mcp"], "env": { "POSTGRES_HOST": "localhost", "POSTGRES_PORT": "5432", "POSTGRES_USER": "your_user", "POSTGRES_PASSWORD": "your_password", "POSTGRES_DB": "your_database" } } } }

Available Tools (14 total)

Query Execution

Tool	Description
`query`	Execute read-only SQL queries against the database
`execute`	Execute write operations (INSERT/UPDATE/DELETE) when enabled
`explain_query`	Get EXPLAIN plan for query optimization

Schema Exploration

Tool	Description
`list_schemas`	List all schemas in the database
`list_tables`	List tables in a specific schema
`describe_table`	Get table structure (columns, types, constraints)
`list_views`	List views in a schema
`describe_view`	Get view definition and columns
`list_functions`	List functions and procedures

Performance & Analysis

Tool	Description
`table_stats`	Get table statistics (row count, size, bloat)
`list_indexes`	List indexes for a table
`list_constraints`	List constraints (PK, FK, UNIQUE, CHECK)

Database Info

Tool	Description
`get_database_info`	Get database version and connection info
`search_columns`	Search for columns by name across all tables

MCP Prompts

Guided workflows that help Claude assist you effectively:

Prompt	Description
`explore_database`	Comprehensive database exploration and overview
`query_builder`	Help building efficient queries for a table
`performance_analysis`	Analyze table performance and suggest optimizations
`data_dictionary`	Generate documentation for a schema

MCP Resources

Browsable database structure:

Resource URI	Description
`postgres://schemas`	List all schemas
`postgres://schemas/{schema}/tables`	Tables in a schema
`postgres://schemas/{schema}/tables/{table}`	Table details
`postgres://database`	Database connection info

Example Usage

Once configured, ask Claude to:

Schema Exploration:

"List all tables in the public schema"
"Describe the users table structure"
"What views are available?"

Querying:

"Show me 10 rows from the orders table"
"Find all customers who placed orders last week"
"Count records grouped by status"

Performance Analysis:

"What indexes exist on the orders table?"
"Analyze the performance of the users table"
"Explain this query: SELECT * FROM orders WHERE created_at > '2024-01-01'"

Documentation:

"Generate a data dictionary for this database"
"What columns contain 'email' in their name?"

Security

This MCP server implements multiple security layers:

Read-Only by Default

Write operations (INSERT, UPDATE, DELETE) are blocked unless explicitly enabled via ALLOW_WRITE_OPERATIONS=true.

SQL Injection Prevention

All queries are validated before execution
Dangerous operations (DROP DATABASE, etc.) are always blocked
Multiple statements are not allowed
SQL comments are blocked

Credential Protection

Passwords stored using secure string types
Credentials never appear in logs or error messages

Query Limits

Results limited by MAX_ROWS (default: 1000)
Query timeout configurable via QUERY_TIMEOUT

Development

TypeScript

cd typescript npm install npm run build npm run dev # Watch mode

Python

cd python uv sync uv run pytest -v --cov=postgres_mcp

Running Tests

# Python unit tests (no database required) cd python uv run pytest tests/test_security.py tests/test_settings.py -v # Integration tests (requires PostgreSQL) docker-compose up -d uv run pytest tests/test_integration.py -v

Troubleshooting

Connection Issues

# Verify PostgreSQL is running pg_isready -h localhost -p 5432 # Test connection with psql psql -h localhost -U your_user -d your_database

Permission Denied

Ensure your database user has SELECT permissions:

GRANT SELECT ON ALL TABLES IN SCHEMA public TO your_user;

MCP Server Not Connecting

# Check server status claude mcp get postgres # Test server directly postgresql-mcp # Should wait for MCP messages

Links

License

MIT

This server cannot be installed

A

security – no known vulnerabilities

A

license - permissive license

A

quality - confirmed to work

How are these scores calculated?

Resources

GitHub Repository

Need Help?

Report Issue

Related Servers

Tools

View all tools

postgres-mcp

PostgreSQL MCP Server

Language Versions

Features

Quick Start

TypeScript (Recommended for Smithery)

Python

Configuration

Environment Variables

Claude Code CLI

Cursor IDE

Available Tools (14 total)

Query Execution

Schema Exploration

Performance & Analysis

Database Info

MCP Prompts

MCP Resources

Example Usage

Security

Read-Only by Default

SQL Injection Prevention

Credential Protection

Query Limits

Development

TypeScript

Python

Running Tests

Troubleshooting

Connection Issues

Permission Denied

MCP Server Not Connecting

Links

License

Resources

Tools

New MCP Servers

Latest Blog Posts

MCP directory API