Postgres MCP: подключение ИИ-агента к базе данных

Сервер Postgres MCP позволяет ИИ-агенту изучать схему PostgreSQL и выполнять запросы через Model Context Protocol. Вы задаёте серверу параметры подключения, а агент вызывает его инструменты, чтобы читать таблицы и отвечать на вопросы о данных.

В этом руководстве мы подключим Cursor к учебной базе через Postgres MCP Pro, создадим отдельную роль и включим режим ограниченного доступа. Результат легко проверить: агент должен найти два активных проекта с общим месячным бюджетом 68 долларов. Попытка изменить эти строки должна вернуть ошибку.

Вы можете создать базу данных с помощью Managed Postgres в Lizard. Процесс MCP работает на вашем компьютере. Те же SQL-команды работают и с вашей локальной базой PostgreSQL.

Как Postgres MCP подключается к вашей базе данных

Агент отправляет вызов инструмента на сервер MCP. Сервер подключается к PostgreSQL, выполняет запрос и возвращает результат. PostgreSQL проверяет права доступа роли базы данных для этого подключения.

Мы используем Postgres MCP Pro, независимый проект с открытым исходным кодом. Он предоставляет инструменты для просмотра схем, чтения структуры таблиц и выполнения SQL. В этой конфигурации Lizard предоставляет базу данных.

Локальное подключение между Cursor и процессом MCP использует stdio. Ваш компьютер должен иметь доступ к серверу базы данных. Результаты запросов могут попадать в контекст вашего ИИ-провайдера, поэтому в этом руководстве используются выдуманные названия проектов и бюджеты.

Что вам понадобится

• Новый экземпляр PostgreSQL или отдельная база для учебного примера с учетной записью владельца, которая может создать базу данных и роль.
• psql на вашем компьютере.
• uv, который запускает нужную версию пакета Python.
• Cursor с включенными пользовательскими серверами MCP.

Мы протестировали вызовы SQL и MCP с PostgreSQL 14.20, Python 3.12.10, postgres-mcp==0.3.0 и mcp==1.30.0. Ниже мы описали результаты и границы проверки.

1. Создание тестовой базы данных Postgres

В новом проекте Lizard добавьте Managed Postgres из панели управления. Если вы уже используете Lizard CLI и связали новый проект, выполните:

lizard add postgres

В панели управления указаны хост, порт, имя базы данных и данные для входа. Следуйте руководству по подключению к Managed Postgres для подключения с помощью psql. Используйте учетную запись владельца для этой настройки; агент получит другую учетную запись.

В psql создайте новую базу данных и подключитесь к ней:

CREATE DATABASE mcp_demo;
\connect mcp_demo

\connect — это команда psql. Если вы используете SQL-редактор, выберите mcp_demo перед выполнением следующего блока. Если имя базы данных уже существует, выберите другое имя и обновите последующие примеры.

Создайте одну таблицу с тремя строками:

CREATE SCHEMA demo;

CREATE TABLE demo.projects (
  id integer PRIMARY KEY,
  name text NOT NULL,
  status text NOT NULL CHECK (status IN ('active', 'paused')),
  monthly_budget_usd numeric(10, 2) NOT NULL
);

INSERT INTO demo.projects VALUES
  (1, 'Atlas', 'active', 49.00),
  (2, 'Beacon', 'active', 19.00),
  (3, 'Cedar', 'paused', 0.00);

Эти суммы относятся к тестовым данным. Это не цены Lizard.

2. Предоставление агенту роли для чтения тестовой таблицы

Создайте роль с правом входа, без прав администратора:

CREATE ROLE mcp_reader LOGIN
  NOSUPERUSER NOCREATEDB NOCREATEROLE NOREPLICATION NOINHERIT;

Затем выполните эту команду psql, чтобы установить пароль, не сохраняя его в истории SQL:

\password mcp_reader

Следующие права доступа предназначены для новой базы данных mcp_demo. Отзыв прав PUBLIC влияет на другие роли, использующие эту базу данных, поэтому не вставляйте этот блок в существующую общую базу данных приложения.

REVOKE ALL ON DATABASE mcp_demo FROM PUBLIC;
REVOKE CREATE ON SCHEMA public FROM PUBLIC;

GRANT CONNECT ON DATABASE mcp_demo TO mcp_reader;
GRANT USAGE ON SCHEMA demo TO mcp_reader;
GRANT SELECT ON demo.projects TO mcp_reader;

ALTER ROLE mcp_reader IN DATABASE mcp_demo
  SET default_transaction_read_only = on;
ALTER ROLE mcp_reader IN DATABASE mcp_demo
  SET statement_timeout = '5s';

Это предоставляет доступ к одной таблице. Таблице, которую вы создадите позже, потребуются собственные права доступа. PostgreSQL все еще может раскрывать имена объектов через системные каталоги; права доступа к таблице контролируют доступ к строкам. См. справочник по GRANT в PostgreSQL.

Настройка только для чтения по умолчанию помогает избежать ошибок, но клиент может изменить этот параметр. Именно права доступа к таблице не позволяют этой роли писать в demo.projects. Мы проверили, что обновление по-прежнему завершается ошибкой после отключения настройки по умолчанию.

3. Сохраните подключение для чтения вне исходного кода

Создайте URL-адрес подключения, используя новую роль и базу данных mcp_demo. Сохраните хост, порт и необходимые настройки TLS из инструкций по подключению вашего провайдера. Используйте процентное кодирование для специальных символов в пароле при добавлении его в URL; PostgreSQL документирует формат URI подключения.

Для удалённой базы, которая требует TLS, адрес выглядит так:

postgresql://mcp_reader:URL_ENCODED_PASSWORD@DB_HOST:DB_PORT/mcp_demo?sslmode=require

sslmode=require требует шифрования. Если ваш провайдер предоставляет CA-сертификат и имя хоста для полной проверки сертификата, используйте его конфигурацию verify-full. При ошибке сертификата проверьте имя хоста и доверенный сертификат. Не отключайте TLS для удалённой базы.

Добавьте .env.mcp в файл .gitignore вашего проекта, затем создайте этот файл в корне проекта:

DATABASE_URI=postgresql://mcp_reader:URL_ENCODED_PASSWORD@DB_HOST:DB_PORT/mcp_demo?sslmode=require

Вместо заглушек укажите данные подключения роли для чтения. Имя должно быть DATABASE_URI: именно этого ожидает Postgres MCP Pro. Переменная подключения приложения Lizard называется DATABASE_URL; передача только этого имени не настроит этот сервер MCP.

Не добавляйте подключение владельца в этот файл. В macOS или Linux ограничьте доступ к этому файлу:

chmod 600 .env.mcp

4. Настройка Postgres MCP в Cursor

Создайте .cursor/mcp.json в том же проекте. Если файл уже содержит другие серверы, добавьте postgres-demo внутрь существующего объекта mcpServers.

{
  "mcpServers": {
    "postgres-demo": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--python", "3.12",
        "--with", "mcp==1.30.0",
        "--from", "postgres-mcp==0.3.0",
        "postgres-mcp", "--access-mode=restricted"
      ],
      "envFile": "${workspaceFolder}/.env.mcp"
    }
  }
}

Cursor поддерживает конфигурацию MCP проекта и envFile для локальных серверов stdio. См. его справочник по конфигурации MCP. Если Cursor не может найти uvx, замените команду на полный путь установки.

Укажите обе версии пакетов. Во время нашей проверки установка postgres-mcp==0.3.0 без ограничения MCP SDK выбрала mcp==2.2.0. После этого сервер не смог импортировать mcp.server.fastmcp. С mcp==1.30.0 он запустился и успешно прошел тесты ниже.

Чтобы проверить запуск пакета перед открытием подключения к базе данных, выполните:

uvx --python 3.12 --with 'mcp==1.30.0' \
  --from 'postgres-mcp==0.3.0' postgres-mcp --help

Включите или перезапустите postgres-demo в настройках MCP Cursor. Оставьте подтверждение инструментов включенным во время проверки настройки и проверяйте аргументы SQL перед разрешением вызова.

5. Проверка инструментов и ответа

Начните с вопроса о схеме:

Use postgres-demo to inspect the demo schema. List its tables and the columns
of demo.projects. Show the tool results. Do not change the database.

Сервер должен предоставлять list_schemas, list_objects, get_object_details и execute_sql. Убедитесь, что агент вызывает инструменты и сообщает о id, name, status и monthly_budget_usd из таблицы.

Затем спросите:

Using demo.projects, how many projects are active and what is their total
monthly budget in USD? Show the SQL and the database result.

Запрос для этого ответа:

SELECT
  count(*) AS active_projects,
  sum(monthly_budget_usd) AS total_budget_usd
FROM demo.projects
WHERE status = 'active';

Ожидаемые значения:

Наконец, проверьте ограничение на этой тестовой таблице. Условие WHERE false гарантирует, что запрос не найдет совпадающих строк:

Use execute_sql to run exactly:
UPDATE demo.projects SET name = name WHERE false;
Report the tool response. Do not retry with another tool or connection.

В нашем тесте режим ограниченного доступа вернул Error: Error validating query. Отдельное прямое подключение с использованием mcp_reader вернуло permission denied for table projects даже после того, как мы отключили его настройку только для чтения по умолчанию. Проверка MCP и права доступа к базе данных отклонили операцию.

Что мы протестировали

24 сентября 2026 года мы выполнили тестовые SQL-запросы и реальные вызовы MCP к новому локальному экземпляру PostgreSQL 14.20 с синтетическими данными. Мы использовали Python 3.12.10, Postgres MCP Pro 0.3.0 и MCP SDK 1.30.0.

Мы проверили права SQL и протокол MCP. Мы не проходили эти шаги в интерфейсе Cursor и не создавали новую базу в Lizard для этого теста. Повторите проверки на своей базе: индикатор подключения MCP ещё не доказывает, что инструменты работают.

Исправление частых ошибок подключения Postgres MCP

Нужны ли вам расширения PostgreSQL?

Запросы к схеме и данным в этом руководстве не требуют дополнительных расширений. В Postgres MCP Pro также есть инструменты анализа производительности. У них свои требования.

Анализ наиболее затратных запросов использует pg_stat_statements. Анализ гипотетических индексов использует hypopg. Доступность, конфигурация сервера и права ролей имеют значение; создание расширения может потребовать действий владельца или изменения сервера. Проверьте требования к расширениям проекта перед использованием этих инструментов.

Начните с проверок схемы и SELECT. Ошибка, связанная с расширением в инструменте настройки, сама по себе не означает, что базовое подключение MCP не работает.

Часто задаваемые вопросы

Postgres MCP — это то же самое, что и Lizard MCP?

Нет. В этом примере используется Postgres MCP Pro для запросов к базе данных PostgreSQL. Managed Postgres предоставляет эту базу данных. Коннектор — это отдельный проект.

Могу ли я использовать другого ИИ-агента?

Да, если его клиент поддерживает локальные серверы MCP через stdio. Используйте процесс с теми же версиями пакетов, данные роли для чтения и режим ограниченного доступа, затем следуйте формату конфигурации этого клиента. JSON выше предназначен для Cursor.

Заменяет ли режим ограниченного доступа права базы данных?

Используйте и то, и другое. Режим ограниченного доступа проверяет запросы на сервере MCP. Права доступа PostgreSQL ограничивают то, что может делать роль подключения, даже через другого клиента. Сохраните учетную запись владельца для миграций и администрирования.

Будет ли он создавать таблицы или выполнять миграции за меня?

Эта настройка даёт роли доступ для чтения учебной таблицы. Роль не может создавать или менять схему приложения. Выполняйте проверенные миграции с помощью вашего обычного процесса развертывания приложения.

Подключите базу к своему приложению

Как только агент сможет изучить тестовую схему и вернуть ожидаемый ответ, у вас появится рабочая основа для вопросов к базе данных во время разработки. Храните данные роли агента для чтения отдельно от учетных данных вашего приложения по мере добавления таблиц.

Создайте Managed Postgres для вашего проекта, следуйте руководству по подключению к базе данных или продолжите с примером развертывания приложения Cursor. Если MCP-сервером будут пользоваться несколько клиентов, см. отдельное руководство по удаленному серверу MCP.