MCP Database Suite

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

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

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

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

Каждый сервер — отдельный бинарник. В простейшем случае он подключается к одной БД через CLI-флаги:

# 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

# Redis
mcp-redis --host=localhost --port=6379

# Memcached
mcp-memcached --host=localhost --port=11211

Один сервер может обслуживать несколько БД (мульти-БД режим) и ограничивать доступ по пользователям из JWT. Для этого используется конфигурационный файл — см. пример config.yml.example и разделы ниже:

mcp-postgres --config=config.yml.example

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

• 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.1.0/mcp-postgres-v1.1.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.1.0/mcp-postgres-v1.1.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.1.0/mcp-postgres-v1.1.0-windows-amd64.exe" -OutFile mcp-postgres.exe

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

Запуск из исходников

Бинарник можно не скачивать, а собрать из исходников. Модуль приватный — добавьте его в свой Go-окружение: go env -w GOPRIVATE=git.ymnuktech.ru/* (или положите репозиторий в локальный чекаут):

# go run — сразу из чекаута тэга
git clone https://git.ymnuktech.ru/ymnuk/mcp-db-suite.git && cd mcp-db-suite
git checkout v1.1.0
go run -ldflags "-X 'git.ymnuktech.ru/ymnuk/mcp-db-suite/internal/version.Version=v1.1.0'" ./cmd/mcp-postgres

# go install — один раз, дальше бинарник лежит в GOBIN
go install -ldflags "-X 'git.ymnuktech.ru/ymnuk/mcp-db-suite/internal/version.Version=v1.1.0'" \
  git.ymnuktech.ru/ymnuk/mcp-db-suite/cmd/mcp-postgres@v1.1.0

• Версия задаётся через -ldflags (см. internal/version.Version); без неё --version покажет devel.
• Тэг релиза должен иметь v-префикс: go install ...@v1.1.0 резолвится в git-тэг v1.1.0.
• go run перекомпилирует при каждом запуске (кэш Go ускоряет повторные). Для постоянного сервера в IDE удобнее go install/go build.

Docker

Каждый сервер — отдельный тег в одном репозитории (scratch base, ~12MB):

# PostgreSQL
docker build --target postgres -t mcp-db-suite:postgres .

# MariaDB
docker build --target mariadb -t mcp-db-suite:mariadb .

# и т.д.

Запуск:

docker run -it mcp-db-suite:v1.1.0-redis --host=redis --port=6379
docker run -it mcp-db-suite:v1.1.0-postgres --host=db --port=5432 --user=admin --password=secret --database=mydb

Запуск:

# Redis (тег v1.1.0-redis)
docker run -it git.ymnuktech.ru/mcp-db-suite:v1.1.0-redis --host=redis --port=6379

# PostgreSQL (тег v1.1.0-postgres)
docker run -it git.ymnuktech.ru/mcp-db-suite:v1.1.0-postgres --host=db --port=5432 --user=admin --password=secret --database=mydb

# Все серверы доступны через теги:
# - mcp-db-suite:latest
# - mcp-db-suite:v1.1.0-postgres
# - mcp-db-suite:v1.1.0-mariadb
# - mcp-db-suite:v1.1.0-sqlite
# - mcp-db-suite:v1.1.0-clickhouse
# - mcp-db-suite:v1.1.0-redis
# - mcp-db-suite:v1.1.0-memcached

TLS с CA certificates:

Образы собираются на scratch (без встроенных сертификатов). Для TLS подключения к БД используй:

# Монтирование системных сертификатов с хоста
docker run -v /etc/ssl/certs/ca-certificates.crt:/etc/ssl/certs/ca-certificates.crt:ro \
  mcp-db-suite:postgres --host=db.example.com --port=5432 ...

Или укажи файл сертификата через env:

export SSL_CERT_FILE=/path/to/cert.crt
docker run -v /path/to/cert.crt:/path/to/cert.crt:ro \
  mcp-db-suite:postgres --host=db.example.com --port=5432 ...

Примечание: Образы собираются для linux/amd64, linux/arm64, linux/arm/v7 (multi-arch через buildx).

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

git clone https://git.ymnuktech.ru/ymnuk/mcp-db-suite
cd mcp-db-suite

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
go build -o mcp-redis     ./cmd/mcp-redis
go build -o mcp-memcached ./cmd/mcp-memcached

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

SQL-серверы (PostgreSQL, MariaDB, SQLite, ClickHouse)

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

Key-Value серверы (Redis, Memcached)

Инструмент	Описание
get	Получить значение по ключу
set	Установить значение (с опциональным TTL)
del	Удалить ключ
keys	Найти ключи по паттерну
ttl	Получить TTL ключа (Redis: >0, Memcached: -1)

Подключение к 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"]
    },
    "redis": {
      "command": "mcp-redis",
      "args": ["--host=localhost", "--port=6379"]
    },
    "memcached": {
      "command": "mcp-memcached",
      "args": ["--host=localhost", "--port=11211"]
    },
    "multi-postgres": {
      "command": "mcp-postgres",
      "args": ["--config=/etc/mcp/mcp-postgres.yaml"]
    }
  }
}

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 --config=cfg.yaml

• MCP endpoint: http://127.0.0.1:8080/mcp
• Health check: http://127.0.0.1:8080/health
• Auth: заголовок Authorization: Bearer <JWT> (см. раздел «Авторизация через JWT»)

В STDIO-режиме логи пишутся в stderr (stdout занят MCP-протоколом), при --log-file/--log-udp-addr — в файл/UDP.

Мульти-БД режим

Один процесс сервера может обслуживать несколько БД одного движка. Все подключения и настройки доступа описываются в одном конфигурационном файле (--config, YAML или JSON). Полный пример — config.yml.example.

dbs:
  - name: prod
    host: db1.example.com
    port: 5432
    user: admin
    password: secret
    database: app

  - name: analytics
    host: db2.example.com
    port: 5432
    user: admin
    password: secret
    database: analytics

Запуск: mcp-postgres --config=/etc/mcp/mcp-postgres.yaml.

Именование инструментов в мульти-БД режиме

• Каждая БД получает префикс по алиасу: prod__exec, analytics__listTables, cache__get.
• Одиночный режим (без --config и dbs:) — инструменты без префикса (exec, listTables) — обратная совместимость.
• Глобальный инструмент listDatabases всегда доступен и возвращает список БД, доступных текущему пользователю:

{
  "databases": [
    { "name": "prod", "engine": "PostgreSQL" },
    { "name": "analytics", "engine": "PostgreSQL" }
  ]
}

Авторизация через JWT

В HTTP Streamable режиме доступ к БД можно ограничить по пользователям из JWT. JWT передаётся в заголовке Authorization: Bearer <token>.

Настройка

В конфигурационном файле:

jwt:
  secret: hmac-secret-123    # HS256-секрет; пусто = декодирование без проверки подписи
  id_claim: sub              # claim с user id (по умолчанию sub)

dbs:
  - name: prod
    id: [alice, bob]         # allowlist: только эти пользователи
    host: db1.example.com
    ...
  - name: analytics
    # id не задан -> БД открыта всем, включая анонимов без JWT
    host: db2.example.com
    ...

Правила доступа

Случай	Результат
Заголовка нет	Аноним — доступны только БД без id (allowlist пуст)
JWT валиден, id есть в id БД	БД доступна
JWT валиден, но id нет в id БД	БД скрыта: тулы name__* не показываются в tools/list, вызов отклоняется
JWT невалиден / просрочен	401 Unauthorized
jwt.secret задан	Подпись проверяется (HS256); неверная подпись → 401
jwt.secret не задан	Подпись не проверяется (только декодирование) — для тестов/локальной разработки

Отказ при вызове

Если LLM вызовет тул закрытой БД, сервер вернёт isError: true:

{
  "isError": true,
  "content": [{ "type": "text", "text": "Access denied: user u3 has no access to tool prod__exec" }]
}

Транспорты

Транспорт	Кто пользователь
HTTP Streamable	Из заголовка Authorization: Bearer <jwt>
STDIO	Аноним (все открытые БД) — сервис считается локальным

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

Любой параметр можно задать через env (префикс зависит от движка):

export MCP_DB_HOST=db.example.com      # PostgreSQL / MariaDB
export MCP_DB_USER=admin
export MCP_DB_PASSWORD=secret
export MCP_DB_NAME=mydb

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

Префиксы env:

• PostgreSQL / MariaDB: MCP_DB_*
• SQLite: MCP_SQLITE_*
• ClickHouse: MCP_CLICKHOUSE_*
• Redis: MCP_REDIS_*
• Memcached: MCP_MEMCACHED_*
• Логирование (все движки): MCP_LOG_FILE, MCP_LOG_UDP_ADDR, MCP_LOG_LEVEL

Приоритет: CLI > env > config-файл > default.

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

Общие для всех серверов:

Флаг	Описание
--config	Путь к конфигурационному файлу (YAML/JSON), мульти-БД режим
--listen	Адрес HTTP/SSE (пусто = STDIO)
--path	Endpoint path для HTTP/SSE (по умолчанию: /mcp)
--log-file	Файл для JSONL-логов (иначе stderr)
--log-udp-addr	UDP-адрес для JSONL-логов
--log-level	Уровень: debug/info/warn/error/off (по умолчанию: info)
--version, -v	Показать версию
--help, -h	Показать справку

SQL-серверы (PostgreSQL, MariaDB, SQLite, ClickHouse)

Флаг	Описание
--host	Хост БД (по умолчанию: localhost)
--port	Порт БД (PostgreSQL: 5432, MariaDB: 3306, ClickHouse: 9000)
--user	Пользователь БД
--password	Пароль
--database	Имя базы данных
--schema	Схема PostgreSQL (по умолчанию: public)
--table-prefix	Префикс таблиц MariaDB
--db-path	Путь к SQLite файлу
--limit	Лимит строк для exec
--db-pool	Размер пула (по умолчанию: 1)

Key-Value серверы (Redis, Memcached)

Флаг	Описание
--host	Хост (по умолчанию: localhost)
--port	Порт (Redis: 6379, Memcached: 11211)
--password	Пароль (Redis)
--database	Номер БД (Redis)
--limit	Лимит для keys (по умолчанию: 100)
--timeout	Таймаут в мс (Memcached, по умолчанию: 100)

Версии

mcp-postgres    --version     # mcp-postgres v1.1.0
mcp-mariadb     --version     # mcp-mariadb v1.1.0
mcp-sqlite      --version     # mcp-sqlite v1.1.0
mcp-clickhouse  --version     # mcp-clickhouse v1.1.0
mcp-redis       --version     # mcp-redis v1.1.0
mcp-memcached   --version     # mcp-memcached v1.1.0

Версия приходит из git-тэга релиза (через -ldflags при сборке); без него выводится devel.

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

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

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

Файл	Описание
config.yml.example	Готовый пример конфигурации со всеми движками
docs/ARCHITECTURE.md	Архитектура, принципы, жизненный цикл запроса
docs/CONFIGURATION.md	Подробное описание параметров для каждой СУБД
docs/LOG-SPECIFICATION.md	Спецификация логирования
docs/SQL-SPECIFICATION.md	Спецификация SQL-инструментов
docs/KEYVAL-SPECIFICATION.md	Спецификация Key-Value инструментов (Redis, Memcached)
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