postgres-mcp

Универсальный, повторно используемый MCP сервер для запросов только на чтение к любой базе данных Postgres через Claude (или любого MCP-совместимого клиента). Он не знает ни одной конкретной схемы — list_tables, describe_table и run_sql работают исключительно на основе information_schema и общей интроспекции jsonb, поэтому его можно направить на любую базу данных Postgres без изменения кода.

Security model

Два независимых уровня, эшелонированная защита:

1. Уровень БД: сервер подключается как роль, которой предоставлен только SELECT, — то есть он не может записывать данные, даже если запрос попытается это сделать. Создайте эту роль с помощью setup_reader_role.sql.

2. Уровень приложения: run_sql() отклоняет всё, что не является обычным SELECT (или WITH ... SELECT), ограничивает результат 200 строками и устанавливает 5-секундный тайм-аут выполнения — всё это работает как быстрая проверка до обращения даже к базе данных.

Related MCP server: pg-mcp

Setup

1. Создайте роль только для чтения в целевой базе данных:

   • Откройте setup_reader_role.sql, замените плейсхолдер пароля и <your_db_name> на реальные значения, затем выполните его один раз в вашей базе данных (например, через psql или консоль SQL вашего провайдера БД).

2. Укажите строку подключения в файле .env в этом каталоге:

   DATABASE_URL=postgresql://mcp_reader:yourpassword@host:5432/yourdb
   ANTHROPIC_API_KEY=sk-ant-...

   (ANTHROPIC_API_KEY потребуется только для chat.py, а не для запуска MCP-сервера.)

3. Установите зависимости:

   pip install -r requirements.txt

Локальное тестирование

Сначала проверьте слой запросов напрямую, без участия MCP-клиента:

python chat.py "what tables do I have?"

Затем протестируйте его как настоящий MCP-сервер с помощью Inspector:

fastmcp dev inspector mcp_server.py

Если у вас возникнут проблемы с инструментальным набором Node.js для Inspector (такое уже случалось), используйте запасной вариант: запустите сервер напрямую через HTTP и обращайтесь к нему с помощью Python-клиента FastMCP:

fastmcp run mcp_server.py --transport http --port 8000

from fastmcp import Client
import asyncio

async def main():
    async with Client("http://localhost:8000/mcp") as client:
        print(await client.call_tool("list_tables", {}))

asyncio.run(main())

Развертывание (Prefect Horizon)

Платформа размещения FastMCP сейчас называется Prefect Horizon (раньше это был «FastMCP Cloud» — брендинг уже менялся, поэтому перед этими шагами сверьте актуальное название и URL на gofastmcp.com/deployment, чтобы убедиться, что название снова не изменилось).

1. Отправьте репозиторий на GitHub — удаленный репозиторий должен существовать (если ещё нет, см. команды git в конце этого README).

2. Перейдите на сайт текущей платформы (на момент написания — horizon.prefect.io) и войдите через GitHub.

3. Подключите этот репозиторий.

4. Настройте развертывание:

   • Входная точка: mcp_server.py:mcp — часть :mcp — это имя переменной, которой присваивается серверный объект в файле (см. строку mcp = FastMCP(...) в mcp_server.py). Если вы переименуете эту переменную или перенесете файл, эту строку входной точки нужно будет изменить, чтобы она точно соответствовала новому имени и пути.

   • Аутентификация: включите её. Интерактивные MCP-клиенты, такие как claude.ai и Claude Desktop, требуют настоящих конечных точек OAuth Discovery для подключения. Сервер без аутентификации не будет работать с такими клиентами, даже если при прямом тестировании с помощью обычного API-вызова или Python-клиента FastMCP всё работает корректно.

   • Переменные окружения: добавьте DATABASE_URL в панель управления платформы. Это значение отдельная от локального файла .env этого проекта и не читается оттуда — его необходимо ввести непосредственно в панели, чтобы развернутый сервер получил доступ к БД.

5. Разверните сервер и скопируйте полученный URL. Он будет выглядеть примерно так: https://<name-вашего-сервера>.fastmcp.app/mcp (фактический домен может отличаться — используйте то, что вам показывает платформа).

6. Прежде чем интегрировать его куда-либо ещё, протестируйте его встроенным инструментом Inspector/тестрования платформы. Сначала вызовите там list_tables — ему не требуется аргументов, поэтому это самый быстрый способ убедиться, что развернутый сервер действительно может достичь вашу базу данных.

Подключение к claude.ai

1. Перейдите в claude.ai → Настройки → Подключения → Добавить собственный коннектор.

2. Вставьте URL развернутого сервера с предыдущего шага.

3. Пройдите шаги OAuth, который он вам предложит.

4. Начните новый диалог (не тот, который был начат до добавления коннектора) и включите коннектор в этом диалоге.

5. Проверьте его простым вопросом, например «какие таблицы у меня есть?»

6. Если позже вы add new tools and they don't appear, в настройках коннектора нажмите "Обновить инструменты", а не считайте, что что-то сломано — это известное поведение кэширования, а не ошибка.

Ограничения

Он действительно не привязан к схеме, но не это значит, что у него всех ограничений:

• Привязано к Postgres. Он использует jsonb_object_keys() и синтаксис каталогов Postgres (information_schema и т. д.). Направить его на MySQL или SQLite потребовало бы реальных изменений кода в db_tools.py, а не просто новой строки подключения.

• Отсутствие привязки к схеме ≠ нулевая настройка для каждой БД. Каждая новая целевая база данных по-прежнему требует использования собственной роли только для чтения (setup_reader_role.sql) и собственного развертывания (или по крайней мере свой DATABASE_URL), чтобы они были на неё. Это не единый сервер, который прозрачно обслуживает несколько баз данных.

Настройка git

Если вы начинаете работать с этим кодом и у вас ещё нет истории git:

git init
git add .
git commit -m "Initial commit: generic read-only Postgres MCP server"
git branch -M main
git remote add origin <your-repo-url>
git push -u origin main