GaussDB MCP

MCP-сервер для облачной базы данных GaussDB от Huawei Cloud. Основан на официальном Node.js-драйвере GaussDB gaussdb-node, соответствует спецификации MCP 2026-07-28, предоставляет 24 инструмента и 1 ресурс структуры таблиц: проверка подключения, запросы, запись данных, транзакции, метаданные, диагностика и эксплуатация, пользователи и права.

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

npm install
cp .env.example .env   # Windows: copy .env.example .env 后编辑
# 编辑 .env,填入 GaussDB 实例地址、密码等
npm run build
node build/index.js    # 启动(stdio,供 MCP 客户端拉起)

Требуется Node.js ≥ 20.

Related MCP server: mcp-db-assistant

Конфигурация подключения

Все переменные окружения

Конфигурация подключения по внутренней сети

Используется, когда приложение и экземпляр GaussDB находятся в одной VPC. SSL не требуется (внутренний трафик не выходит наружу, официально Huawei Cloud рекомендует прямое подключение по внутренней сети):

GAUSSDB_HOST=10.0.1.11              # 实例"节点列表"中的内网地址
GAUSSDB_PORT=8000
GAUSSDB_DATABASE=postgres
GAUSSDB_USER=root
GAUSSDB_PASSWORD=你的密码
# 不设置任何 GAUSSDB_SSL_* 变量,保持 GAUSSDB_SSL=0(默认)

Конфигурация подключения по публичной сети

Используется, когда приложение находится вне VPC экземпляра и обращается через эластичный публичный IP. Необходимо включить SSL и настроить сертификат CA (официальный способ Huawei Cloud sslmode=verify-ca):

GAUSSDB_HOST=114.114.114.114        # 实例绑定的弹性公网 IP
GAUSSDB_PORT=8000
GAUSSDB_DATABASE=postgres
GAUSSDB_USER=root
GAUSSDB_PASSWORD=你的密码
GAUSSDB_SSL=1
GAUSSDB_SSL_CA=C:/path/to/root.crt   # 华为云控制台下载的 CA 证书(公网连接必需)
GAUSSDB_SSL_REJECT_UNAUTHORIZED=true

Перед подключением по публичной сети также необходимо разрешить доступ к порту 8000 с исходящего IP клиента в группе безопасности консоли Huawei Cloud.

Как добавить переменные окружения

Два способа, на выбор (при одновременном использовании переменные окружения имеют приоритет над .env):

1. Файл .env проекта (рекомендуется): скопируйте .env.example в .env в корне проекта и заполните. Расположение .env привязано к корню проекта и не зависит от того, из какой директории запущен сервер — MCP-клиент сможет прочитать его при запуске build/index.js из любого рабочего каталога. Обе конфигурации выше можно просто записать в .env.

2. Поле env MCP-клиента: передавайте переменные окружения напрямую в конфигурации mcpServers (см. примеры подключения ниже), подходит для сценариев, когда не хочется хранить файлы с учётными данными в проекте.

При ведущем/ведомом развёртывании GAUSSDB_HOST содержит несколько IP-адресов узлов через запятую; при запуске сервер последовательно пробует подключиться и автоматически выбирает первый доступный узел.

Обзор инструментов (24)

Все инструменты помечены аннотациями в соответствии со спецификацией MCP (readOnlyHint/destructiveHint), клиент может на их основе показывать подтверждение для операций записи.

Подключение и статус

Запросы и запись

Транзакции (явный режим handle)

Использование: transaction_begin → несколько query/execute (передавая один и тот же tx_handle) → transaction_commit или transaction_rollback.

Метаданные (только чтение)

Диагностика и эксплуатация (только чтение)

Пользователи и права

Ресурсы

Подключение MCP-клиента

После сборки зарегистрируйте в конфигурационном файле клиента (на примере формата mcpServers для Claude Desktop / Cursor). В Windows используйте пути с двойной обратной косой чертой (E:\\MCP\\GaussDBMCP\\build\\index.js), в Linux/macOS — с прямой (/home/user/GaussDBMCP/build/index.js).

Подключение по внутренней сети

{
  "mcpServers": {
    "gaussdb": {
      "command": "node",
      "args": ["E:\\MCP\\GaussDBMCP\\build\\index.js"],
      "env": {
        "GAUSSDB_HOST": "10.0.1.11",
        "GAUSSDB_PORT": "8000",
        "GAUSSDB_DATABASE": "postgres",
        "GAUSSDB_USER": "root",
        "GAUSSDB_PASSWORD": "你的密码"
      }
    }
  }
}

Для внутренней сети SSL не требуется, не задавайте никаких переменных GAUSSDB_SSL_*.

Подключение по публичной сети

{
  "mcpServers": {
    "gaussdb": {
      "command": "node",
      "args": ["E:\\MCP\\GaussDBMCP\\build\\index.js"],
      "env": {
        "GAUSSDB_HOST": "114.114.114.114",
        "GAUSSDB_PORT": "8000",
        "GAUSSDB_DATABASE": "postgres",
        "GAUSSDB_USER": "root",
        "GAUSSDB_PASSWORD": "你的密码",
        "GAUSSDB_SSL": "1",
        "GAUSSDB_SSL_CA": "C:\\path\\to\\root.crt",
        "GAUSSDB_SSL_REJECT_UNAUTHORIZED": "true"
      }
    }
  }
}

Для публичной сети необходимо включить SSL и настроить сертификат CA, а также убедиться, что группа безопасности разрешает доступ к порту 8000 с исходящего IP клиента.

Можно также не передавать env, а полагаться на файл .env в корне проекта (сервер автоматически читает его при запуске, привязка к корню проекта, не зависит от каталога запуска).

Изоляция мультитенантности (stream = schema)

GAUSSDB_SEARCH_PATH одновременно служит белым списком схем на уровне MCP: после настройки доступ ограничивается собственной схемой соответствующего stream, таблицы других stream не видны.

Перехват на уровне MCP (надёжный, основан на структурных параметрах):

• list_schemas возвращает только схемы из белого списка, не раскрывая имена других схем

• list_tables/list_indexes/list_views/list_sequences без явного schema по умолчанию привязываются к первой схеме из белого списка, больше не возвращают таблицы всей базы

• describe_table/insert_rows/update_rows/delete_rows при явной передаче schema, не входящей в белый список, немедленно отклоняются с ошибкой

• Ресурс структуры таблицы gaussdb://{schema}/{table}/schema также ограничен белым списком, чтение через schema отклоняется

Подстраховка на уровне прав базы данных (обязательна, нельзя пропускать): execute — это произвольный SQL, уровень MCP не выполняет разбор SQL (у рукописного парсера всегда найдутся пути обхода); query хотя и принудительно read-only (белый список первых ключевых слов + чёрный список ключевых слов записи + запрет множественных инструкций), но функции с побочными эффектами в форме SELECT (например, pg_terminate_backend, setval) невозможно исчерпывающе перехватить. Доступ между схемами и функции с побочными эффектами обеспечиваются правами GaussDB. Каждый stream использует отдельную ограниченную учётную запись, авторизуется только собственная схема:

-- 以管理员执行:为 stream 建受限账号,只授予自己 schema 的权限
CREATE USER gycwd_app WITH PASSWORD 'xxx' LOGIN;
REVOKE ALL ON DATABASE postgres FROM PUBLIC;            -- 收紧库级默认权限
GRANT CONNECT ON DATABASE postgres TO gycwd_app;
GRANT USAGE ON SCHEMA gycwd TO gycwd_app;               -- 只给自己的 schema
GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA gycwd TO gycwd_app;
-- 该账号未授予其他 schema 的 USAGE,即使手写跨 schema SQL 也会被数据库拒绝

Затем в .env: GAUSSDB_USER=gycwd_app, GAUSSDB_SEARCH_PATH=gycwd, два уровня叠加: структурные входы перехватывает MCP, произвольный SQL — база данных.

Замечания по безопасности

• Журналы stdio-сервера пишутся в stderr, stdout используется только для сообщений MCP

• В структурных инструментах (insert_rows/update_rows/delete_rows и др.) имена таблиц/столбцов/пользователей и другие идентификаторы проходят проверку символов, значения всегда передаются через параметризованные плейсхолдеры, защита от SQL-инъекций; query/explain_query — свободные SQL-входы, суженные проверкой read-only и ограничением одной инструкции (см. выше)

• delete_rows/update_rows принудительно требуют условие where

• explain_query с analyze=true реально выполняет инструкцию, допускаются только SELECT/WITH в начале, автоматически оборачивается в откат транзакции (продвижение последовательностей, побочные эффекты функций не откатываются)

• Инструкции DROP/TRUNCATE и т.п. можно выполнить через execute; клиенту следует полагаться на аннотацию destructiveHint для подтверждения

• Не коммитьте .env в систему контроля версий

Разработка и сборка

npm run build   # tsc 编译到 build/

Структура исходного кода: src/config.ts (конфигурация), src/db.ts (пул соединений и дескрипторы транзакций), src/sql.ts (построение SQL и проверка read-only), src/format.ts (форматирование результатов), src/index.ts (MCP-сервер и регистрация инструментов).

После получения реального экземпляра GaussDB: заполните .env → npm run build → node build/index.js и протестируйте с любым MCP-клиентом; или сначала проверьте подключение отдельно: настройте env и запустите инструмент test_connection.