PostgreSQL MCP

A Model Context Protocol (MCP) server that provides AI assistants (like Claude) with tools to directly interact with PostgreSQL databases securely.

<img src="./demo.png"/> <img src="./pgadmin.png"/>

Features

• create_table: Create a new table with custom columns.
• list_tables: List all tables in the public schema.
• describe_table: Get the schema and column details of a specific table.
• execute_sql: Execute arbitrary SQL queries.
• Web Configurator: A built-in local web UI to securely manage connection strings and generate API keys.

Installation

You can install and run this package easily using uv:

# Run without installing globally
uvx postgresql-mcp

# Or install globally for easy access
uv tool install postgresql-mcp

Setup & Configuration

This project requires an API Key mapped to your PostgreSQL database URL. To easily set this up, we provide a built-in Web Configurator.

1. Generate an API Key

Run the web configurator:

postgresql-mcp-web

Or, if running without global installation:

uvx --from . postgresql-mcp-web

Open your browser to http://localhost:8000. Enter your database URL (postgresql://user:pass@host/db) and click "Generate API Key".

The application securely stores your credentials in ~/.sql-mcp/keys.json and outputs a configuration snippet.

2. Connect Claude Desktop

Copy the generated snippet and add it to your Claude Desktop configuration file (typically located at %APPDATA%\Claude\claude_desktop_config.json on Windows or ~/Library/Application Support/Claude/claude_desktop_config.json on macOS).

{
  "mcpServers": {
    "postgresql-mcp": {
      "command": "uvx",
      "args": [
        "postgresql-mcp"
      ],
      "env": {
        "API_KEY": "postgresql-mcp-your-generated-key"
      }
    }
  }
}

Restart Claude Desktop, and your AI assistant will now be able to interact with your database!

Usage Tracking

The server automatically tracks how many times each API key is utilized. You can view this data locally in ~/.sql-mcp/usage.json.

Contributing

We welcome contributions! Please see CONTRIBUTING.md for details on how to get started.