mapeg-postgres-mcp 1.0.0

PostgreSQL MCP server for Model Context Protocol

PostgreSQL MCP Server

A Model Context Protocol (MCP) server for PostgreSQL databases. Query, explore, and analyze your PostgreSQL databases directly from any MCP-compatible AI client.

Features

• Execute SQL — Run any SQL query with automatic result formatting
• Natural Language Queries — Ask questions in plain English or Turkish
• Schema Exploration — List tables, describe columns, view statistics
• Execution Plans — EXPLAIN / EXPLAIN ANALYZE with buffer stats
• Query History — Review past queries scoped to your database and workspace
• Read-Only Mode — Optional write protection via READ_ONLY=true
• Zero Install — Works with uvx, no virtual environment needed

Quick Start

Claude Code

claude mcp add postgres \
  -e DB_HOST=localhost \
  -e DB_PORT=5432 \
  -e DB_NAME=mydb \
  -e DB_USER=postgres \
  -e DB_PASSWORD=secret \
  -- uvx mapeg-postgres-mcp

Claude Desktop

Add to your config file:

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

{
  "mcpServers": {
    "postgres": {
      "command": "uvx",
      "args": ["mapeg-postgres-mcp"],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "5432",
        "DB_NAME": "mydb",
        "DB_USER": "postgres",
        "DB_PASSWORD": "secret"
      }
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "postgres": {
      "command": "uvx",
      "args": ["mapeg-postgres-mcp"],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "5432",
        "DB_NAME": "mydb",
        "DB_USER": "postgres",
        "DB_PASSWORD": "secret"
      }
    }
  }
}

Windsurf

Add to Windsurf MCP config:

{
  "mcpServers": {
    "postgres": {
      "command": "uvx",
      "args": ["mapeg-postgres-mcp"],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "5432",
        "DB_NAME": "mydb",
        "DB_USER": "postgres",
        "DB_PASSWORD": "secret"
      }
    }
  }
}

VS Code

Add to your VS Code settings (JSON):

"mcp": {
  "servers": {
    "postgres": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mapeg-postgres-mcp"],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "5432",
        "DB_NAME": "mydb",
        "DB_USER": "postgres",
        "DB_PASSWORD": "secret"
      }
    }
  }
}

Gemini CLI

Add to ~/.gemini/settings.json:

{
  "mcpServers": {
    "postgres": {
      "command": "uvx",
      "args": ["mapeg-postgres-mcp"],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "5432",
        "DB_NAME": "mydb",
        "DB_USER": "postgres",
        "DB_PASSWORD": "secret"
      }
    }
  }
}

GitHub Copilot

Add to ~/.copilot/mcp-config.json:

{
  "mcpServers": {
    "postgres": {
      "command": "uvx",
      "args": ["mapeg-postgres-mcp"],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "5432",
        "DB_NAME": "mydb",
        "DB_USER": "postgres",
        "DB_PASSWORD": "secret"
      }
    }
  }
}

OpenAI Codex

Add to ~/.codex/config.toml:

[mcp_servers.postgres]
command = "uvx"
args = ["mapeg-postgres-mcp"]

[mcp_servers.postgres.env]
DB_HOST = "localhost"
DB_PORT = "5432"
DB_NAME = "mydb"
DB_USER = "postgres"
DB_PASSWORD = "secret"

Install from Source

cd mapeg-postgres-mcp
pip install -e .

Configuration

Environment Variable	Required	Default	Description
DB_HOST	No	localhost	PostgreSQL host
DB_PORT	No	5432	PostgreSQL port
DB_NAME	Yes	—	Database name
DB_USER	No	postgres	Database user
DB_PASSWORD	Yes	—	Database password
READ_ONLY	No	false	Block write operations (INSERT, UPDATE, DELETE, DROP, etc.)

Tools

execute_sql — Run SQL queries

Execute any SQL query on the connected PostgreSQL database.

Parameter	Type	Required	Description
sql	string	Yes	SQL query to execute
limit	integer	No	Max rows to return (default: 100)

natural_language_query — Query in plain language

Convert natural language to SQL and execute. Supports Turkish and English.

Parameter	Type	Required	Description
query	string	Yes	Natural language query

Examples: "show all tables", "tabloları listele", "show database info"

describe_table — Table structure details

Get column definitions, row count, and table size.

Parameter	Type	Required	Description
table_name	string	Yes	Table name (schema.table or table)

smart_query — AI-powered query assistant

Analyzes your schema and suggests queries based on your question.

Parameter	Type	Required	Description
question	string	Yes	Question about your data

explain_query — Execution plan analysis

Show the EXPLAIN plan for a SQL query.

Parameter	Type	Required	Description
sql	string	Yes	SQL query to explain
analyze	boolean	No	Run EXPLAIN ANALYZE (default: false)
format	string	No	Output format: text, json, yaml (default: text)
buffers	boolean	No	Include buffer usage (requires analyze=true)

get_query_history — Review past queries

Retrieve recent query history scoped to this database and workspace.

Parameter	Type	Required	Description
limit	integer	No	Number of entries (default: 20)
status	string	No	Filter: success or error
tool_name	string	No	Filter by tool name

Resources

URI	Description
postgresql://tables	List all user tables
postgresql://schema	Detailed schema with columns
postgresql://stats	Database version and statistics

License

MIT