Postgres Mcp

io.github.sparta2025Published by GitHub account sparta2025v0.4.2Updated Oct 24, 2026

PostgreSQL MCP server with 15 tools (SQL, EXPLAIN, health, indexes) plus a Gradio UI with LLM chat.

VerifiedSTDIODesktop onlyDatabasesDeveloper ToolsData & Analytics

Overview

AI-generated overview

A local MCP server for PostgreSQL that lets an assistant inspect schemas, run SQL, read EXPLAIN plans, check database health and get index recommendations.

What you can do
List schemas, tables, views and object details, and read database version, size, extensions and uptime. Run SQL and format queries, with EXPLAIN plans and hypothetical-index simulation. Check database health, active queries, locks, table and index sizes, and the slowest queries. Analyze index usage and get index recommendations. Manage Fernet encryption certificates and list the server's own tools.
When to use it
Useful when an assistant should work directly against a PostgreSQL database: exploring a schema, diagnosing slow queries, reviewing health and locks, or testing index ideas before changing anything.
Requirements
Runs locally over stdio (SSE also supported). Needs a reachable PostgreSQL database and a connection URL supplied in the DATABASE_URL environment variable; the README examples use DATABASE_URI instead. Install via pipx or uv (Python 3.12+) or Docker. Optional pg_stat_statements and hypopg extensions enable query and index analysis.
Before you install
The connection URL contains database credentials and is passed as an environment variable. The README states the standalone server always executes the SQL it is given and that the read-only access mode applies only to the legacy server, so restrict rights on the database user side. SQL execution can change or delete data. An optional LLM optimization feature uses an OpenAI API key.

Installation

In SourceWeft

  1. Open Postgres Mcp in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

📘 Postgres MCP Pro — сервер MCP для PostgreSQL

[Postgres MCP Pro Logo]

[Лицензия: MIT] [Версия PyPI] [Discord] [Twitter Follow] [Contributors]

🔎 Обзор

Postgres MCP Pro — это open-source сервер Model Context Protocol (MCP), предназначенный для помощи разработчикам и AI-агентам на всех этапах разработки: от начального кода и тестирования до деплоя и продакшн-оптимизации.

🙌 Основано на crystaldba/postgres-mcp (MIT, © 2025 Crystal Corp / Johann Schleier-Smith). Форк развивается и поддерживается sparta2025 — автономный MCP-сервер, Gradio-оболочка, LLM-чат с tool-calling, сертификаты шифрования.

📚 Полная документация: docs/DOCUMENTATION.md — развёртывание (Docker/облако), Gradio-оболочка, подключение клиентов (stdio/SSE), все инструменты и переменные окружения.

Отличается от простого подключения к базе данных следующими возможностями:

  • Анализ состояния БД: индекс, буферный кэш, autovacuum, последовательности, репликация и др.
  • Оптимизация индексов: автоматический подбор лучших индексов с помощью промышленных алгоритмов.
  • Планы выполнения: EXPLAIN и симуляция с гипотетическими индексами.
  • Интеллект схемы: генерация SQL с учётом структуры базы.
  • Безопасное выполнение SQL: поддержка режима только для чтения и защита в продакшне.

Поддерживает транспорты: stdio и SSE.

Запуск проекта и причины его создания

📺 Демонстрация

От медленного к молниеносному AI сгенерировал приложение на SQLAlchemy ORM — но оно было слишком медленным. Postgres MCP Pro с Cursor решил проблему за считанные минуты.

  • 🚀 Оптимизация ORM-запросов, индексации и кэширования
  • 🛠️ Исправление сломанной страницы
  • 🧠 Улучшение вывода "топ-фильмов" путём анализа данных и корректировки запросов

👉 Подробнее: movie-app.md

⚡ Быстрый старт

Требования:

  1. Доступ к вашей базе данных PostgreSQL
  2. Docker или Python 3.12+
Удостоверьтесь в доступе:

Пример — подключение через psql или pgAdmin

💡 Для запуска через docker compose заранее создайте пустые файлы хранилищ подключений (иначе Docker смонтирует каталоги вместо файлов):

bash
touch connections.json llm_connections.json

Установка

🐳 Docker
bash
docker pull crystaldba/postgres-mcp
🐍 Python (через pipx)
bash
pipx install postgres-mcp-pro

или через uv:

bash
uv pip install postgres-mcp-pro

Консольная команда после установки — postgres-mcp (автономный MCP-сервер, stdio по умолчанию; --transport sse для SSE).

⚙️ Настройка AI-ассистента (на примере Claude Desktop)

Откройте конфигурационный файл:

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

Пример конфигурации:

Через Docker
json
{  "mcpServers": {    "postgres": {      "command": "docker",      "args": [        "run", "-i", "--rm", "-e", "DATABASE_URI",        "crystaldba/postgres-mcp", "--access-mode=unrestricted"      ],      "env": {        "DATABASE_URI": "postgresql://username:password@localhost:5432/dbname"      }    }  }}
Через pipx
json
{  "mcpServers": {    "postgres": {      "command": "postgres-mcp",      "args": ["--access-mode=unrestricted"],      "env": {        "DATABASE_URI": "postgresql://username:password@localhost:5432/dbname"      }    }  }}
Через uv
json
{  "mcpServers": {    "postgres": {      "command": "uv",      "args": [        "run", "postgres-mcp", "--access-mode=unrestricted"      ],      "env": {        "DATABASE_URI": "postgresql://username:password@localhost:5432/dbname"      }    }  }}
Режимы доступа:
  • --access-mode=unrestricted: полный доступ (dev)
  • --access-mode=restricted: только чтение (prod)

⚠️ Флаг --access-mode поддерживает только легаси-сервер (python -m postgres_mcp.server). Автономный MCP-сервер (postgres_mcp.autonomous.mcp_server) всегда выполняет переданный SQL; разграничение делайте на стороне пользователя БД.

🔄 SSE Transport

Чтобы использовать SSE:

bash
docker run -p 8000:8000 \  -e DATABASE_URI=postgresql://username:password@localhost:5432/dbname \  crystaldba/postgres-mcp --access-mode=unrestricted --transport=sse

Пример для Cursor:

json
{  "mcpServers": {    "postgres": {      "type": "sse",      "url": "http://localhost:8000/sse"    }  }}

🧩 Установка расширений (опционально)

Нужно для:

  • pg_stat_statements — для анализа запросов
  • hypopg — симуляция индексов
sql
CREATE EXTENSION IF NOT EXISTS pg_stat_statements;CREATE EXTENSION IF NOT EXISTS hypopg;

🧪 Примеры использования

  • Проверка БД: "Check the health of my database..."
  • Медленные запросы: "What are the slowest queries..."
  • Рекомендации: "How can I make it faster?"
  • Индексы: "Suggest indexes to improve performance"
  • Оптимизация запроса: "Help me optimize this query: SELECT ..."

📡 MCP API (интерфейс)

Автономный сервер (postgres_mcp.autonomous.mcp_server) предоставляет 15 MCP tools:

ToolНазначение
list_schemasСписок схем БД
list_objectsСписок таблиц, представлений и т.п.
get_object_detailsПодробности по объекту
execute_sqlВыполнение SQL
explain_queryEXPLAIN план запроса
analyze_db_healthЗдоровье БД по множеству метрик
get_top_queriesСамые медленные запросы (pg_stat_statements)
analyze_index_performanceАнализ использования индексов
get_active_queriesВыполняющиеся запросы
get_table_sizesРазмеры таблиц/индексов
get_database_locksТекущие блокировки
format_sql_queryФорматирование SQL (sqlparse)
get_database_infoВерсия, размер БД, расширения, uptime
manage_encryption_keyУправление Fernet-сертификатами
list_toolsСписок всех инструментов сервера

📌 Отличия от других MCP-серверов

Postgres MCP ProДругие MCP-серверы
✅ Проверки здоровья с гарантией❌ Генерация LLM
✅ Оптимизация индексов алгоритмом❌ Гипотетические советы
✅ Симуляции EXPLAIN❌ "Попробуй сам"
✅ Детальный workload-анализ❌ Нет анализа запросов

🧠 Почему нужны инструменты MCP?

LLM отлично справляется с генерацией SQL, но медленно, дорого и непредсказуемо. Оптимизация БД давно решается алгоритмами. MCP Pro сочетает лучшее от LLM и классических алгоритмов.

🛠️ Технические заметки (ключевые моменты)

  • Индексы: использование pg_stat_statements, генерация кандидатов, анализ через hypopg
  • LLM-оптимизация: экспериментальная, с использованием OpenAI API (OPENAI_API_KEY)
  • Здоровье БД: адаптация проверок из PgHero
  • Библиотека подключения: psycopg3 с libpq
  • Безопасность SQL: чтение, защита от ROLLBACK; DROP ...
  • Интеграция со схемой: передаёт схему агенту через инструменты, а не ресурсы
  • Конфигурация соединений: через переменные среды
  • Dev-сборка: uv, pip, запуск с локальной БД

Source: README.md at commit 1b135ec

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.4.2LatestSep 16, 2026

Score

40% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts

    Declare a license in the repository or the registry entry.