MCP Database Suite

Набор MCP-серверов для взаимодействия LLM-агентов с популярными СУБД.

Поддерживаемые СУБД

СУБД	Бинарник	Статус	Порт по умолчанию
PostgreSQL	mcp-postgres	✅ Реализовано	5432
SQLite	mcp-sqlite	✅ Реализовано	—
MariaDB	mcp-mariadb	✅ Реализовано	3306
ClickHouse	mcp-clickhouse	✅ Реализовано	9000
Redis	mcp-redis	🔜 Phase 3	—

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

Каждый сервер — отдельный бинарник, который подключается к одной БД. Запустите столько экземпляров, сколько нужно:

# PostgreSQL
mcp-postgres --host=localhost --port=5432 --user=admin --password=secret --database=mydb

# MariaDB
mcp-mariadb --host=localhost --port=3306 --user=admin --password=secret --database=mydb

# SQLite
mcp-sqlite --db-path=/data/mydb.sqlite

# ClickHouse
mcp-clickhouse --host=localhost --port=9000 --user=default --password=secret --database=default

Серверы работают в двух режимах:

• STDIO (по умолчанию) — для подключения к IDE (Cursor, VS Code, Claude Desktop)
• HTTP/SSE — для веб-приложений и удалённого доступа

Установка

Бинарники

Скачайте готовый бинарник из Releases:

# Linux x86_64
curl -fsSL "https://git.ymnuktech.ru/ymnuk/mcp-db-suite/releases/download/v1.0.0/mcp-postgres-v1.0.0-linux-amd64" \
  -o ~/.local/bin/mcp-postgres && chmod +x ~/.local/bin/mcp-postgres

# Linux ARM64
curl -fsSL "https://git.ymnuktech.ru/ymnuk/mcp-db-suite/releases/download/v1.0.0/mcp-postgres-v1.0.0-linux-arm64" \
  -o ~/.local/bin/mcp-postgres && chmod +x ~/.local/bin/mcp-postgres

# Windows x64
Invoke-WebRequest -Uri "https://git.ymnuktech.ru/ymnuk/mcp-db-suite/releases/download/v1.0.0/mcp-postgres-v1.0.0-windows-amd64.exe" -OutFile mcp-postgres.exe

Доступные платформы: linux/amd64, linux/arm64, linux/armv7, windows/amd64.

Docker

docker run -i git.ymnuktech.ru/ymnuk/mcp-db-suite:latest \
  mcp-postgres --host=host.docker.internal --port=5432 --user=admin --password=secret --database=mydb

Docker-образ поддерживает linux/amd64, linux/arm64, linux/arm/v7.

Из исходников

go build -o mcp-postgres   ./cmd/mcp-postgres
go build -o mcp-mariadb    ./cmd/mcp-mariadb
go build -o mcp-sqlite     ./cmd/mcp-sqlite
go build -o mcp-clickhouse ./cmd/mcp-clickhouse

Доступные инструменты

Каждый сервер предоставляет LLM четыре инструмента:

Инструмент	Описание
listTables	Список таблиц и их описания
listColumns	Столбцы указанной таблицы
exec	Выполнить SQL-запрос (SELECT, INSERT, UPDATE, DELETE, DDL)
explain	План выполнения SQL-запроса

Подключение к IDE

Cursor / VS Code (mcp.json)

{
  "mcpServers": {
    "postgres": {
      "command": "mcp-postgres",
      "args": [
        "--host=localhost",
        "--port=5432",
        "--user=admin",
        "--password=secret",
        "--database=mydb"
      ]
    },
    "sqlite": {
      "command": "mcp-sqlite",
      "args": ["--db-path=/data/mydb.sqlite"]
    }
  }
}

Claude Desktop

{
  "mcpServers": {
    "mariadb": {
      "command": "mcp-mariadb",
      "args": [
        "--host=localhost",
        "--port=3306",
        "--user=admin",
        "--password=secret",
        "--database=mydb",
        "--table-prefix=wp_"
      ]
    },
    "clickhouse": {
      "command": "mcp-clickhouse",
      "args": [
        "--host=localhost",
        "--port=9000",
        "--user=default",
        "--password=secret",
        "--database=default"
      ]
    }
  }
}

HTTP/SSE режим

Для удалённого доступа или веб-приложений:

mcp-postgres --host=localhost --user=admin --database=mydb \
  --listen=127.0.0.1:8080 --api-key=secret

• MCP endpoint: http://127.0.0.1:8080/mcp
• Health check: http://127.0.0.1:8080/health
• Auth: заголовок Authorization: Bearer secret

Конфигурация через переменные окружения

Любой параметр можно задать через env:

export MCP_DB_HOST=db.example.com
export MCP_DB_USER=admin
export MCP_DB_PASSWORD=secret
export MCP_DB_NAME=mydb

mcp-postgres  # подключится к db.example.com

Приоритет: CLI > env > default.

Опции командной строки

Флаг	Описание
--host	Хост БД (по умолчанию: localhost)
--port	Порт БД (PostgreSQL: 5432, MariaDB: 3306, ClickHouse: 9000)
--user	Пользователь БД (обязательный)
--password	Пароль
--database	Имя базы данных (обязательный)
--schema	Схема PostgreSQL (по умолчанию: public)
--table-prefix	Префикс таблиц MariaDB (например wp_)
--db-path	Путь к SQLite файлу
--limit	Лимит строк для exec (по умолчанию: 100, 0 = без лимита)
--db-pool	Размер пула (по умолчанию: 1 = последовательно)
--listen	Адрес HTTP/SSE (пусто = STDIO режим)
--api-key	API-ключ для HTTP/SSE
--version, -v	Показать версию
--help, -h	Показать справку

Версии

mcp-postgres --version     # mcp-postgres 1.0.0
mcp-mariadb --version      # mcp-mariadb 1.0.0
mcp-sqlite --version       # mcp-sqlite 1.0.0
mcp-clickhouse --version   # mcp-clickhouse 1.0.0

При запуске сервер также выводит версию в лог:

[mcp-postgres] Version: 1.0.0
[mcp-postgres] Connected to PostgreSQL at localhost:5432/mydb (schema=public)
[mcp-postgres] Starting in STDIO mode

Безопасность

• Read-only — ограничение через учётную запись БД. Сервер выполняет любой SQL, поэтому создавайте пользователя без прав на запись.
• Пароли — передаются отдельным параметром, не в DSN-строке. Никаких проблем со спецсимволами.
• HTTP-аутентификация — Bearer token через --api-key. Для TLS используйте reverse proxy (nginx, caddy).

Документация

Файл	Описание
docs/ARCHITECTURE.md	Архитектура, принципы, жизненный цикл запроса
docs/CONFIGURATION.md	Подробное описание параметров для каждой СУБД
docs/SQL-SPECIFICATION.md	Спецификация инструментов (вход/выход, примеры)
docs/ROADMAP.md	План развития проекта
docs/DECISIONS.md	Обоснования архитектурных решений (FAQ)

Разработка

# Тесты
go test ./internal/... -count=1

# С race detector
go test ./internal/... -race

# Покрытие
go test ./internal/... -coverprofile=cover.out
go tool cover -func=cover.out

Лицензия

MIT