@cocaxcode/database-mcp

Краткий обзор

Самый полный MCP-сервер для баз данных. 33 инструмента для трёх движков (PostgreSQL, MySQL, SQLite) с группами подключений, управлением именованными подключениями, автоматическим откатом, дампом/восстановлением, автообнаружением схемы через MCP Resources и полной историей запросов — всё на естественном языке.

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

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

Вы описываете, что вам нужно. ИИ читает вашу схему, пишет SQL и безопасно выполняет его — с автоматической подстановкой LIMIT, снимками до мутации и подтверждением перед разрушительными операциями. Никаких облачных аккаунтов, ORM и конфигурационных файлов. Учётные данные никогда не покидают вашу машину. Всё работает локально.

Работает с Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, Codex CLI, Gemini CLI и любым MCP-совместимым клиентом.

Related MCP server: Database MCP Server

Просто скажите

Вам не нужно запоминать названия инструментов или синтаксис SQL. Просто скажите, что вам нужно.

> "Connect to my local PostgreSQL on port 5432, database myapp, user admin"

> "Create a group called backend and add this directory"

> "Connect to my PostgreSQL on localhost, put it in the backend group"

> "Set local-pg as the default connection"

> "Show me all tables"

> "What columns does the users table have?"

> "Show me the last 10 orders with the customer name"
  -> AI reads FKs from schema, builds the JOIN, applies LIMIT 10

> "Insert a test user called Alice"
  -> Snapshot captured for rollback

> "Oops, undo that"
  -> Rows restored via reverse SQL

> "Switch to the production database for this session"
  -> Instant context change, all queries now go to prod

> "Delete all inactive users"
  -> "This will affect N rows. Call again with confirm=true to proceed."

> "What did I run today?"
  -> Full query history with timestamps and execution times

> "Dump the database — structure and data"
  -> SQL file generated, ready for restore

ИИ уже знает вашу схему через MCP Resources. Он читает db://schema, чтобы обнаружить таблицы, и db://tables/{name}/schema для столбцов, внешних ключей и индексов. Когда вы запрашиваете данные из нескольких таблиц, он автоматически строит корректные JOIN.

Группы подключений

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

У группы есть три ключевых понятия:

• Области действия: каталоги, которые используют подключения группы. Когда вы работаете в каталоге, входящем в область действия, вы видите только подключения этой группы. Никакого глобального мусора.

• По умолчанию: подключение, которое активируется автоматически при входе в каталог области действия. Сохраняется между сессиями.

• Активное: подключение, используемое прямо сейчас. Только для сессии — при перезапуске сбрасывается на подключение по умолчанию.

Вот практический пример рабочего процесса:

"Create a group called backend"
"Add this directory as scope"
"Create a PostgreSQL connection called local-dev in the backend group"   <- auto-default (first connection)
"Create another called production in backend"
"List connections"                                                       <- shows local-dev (active, default)
"Switch to production"                                                   <- session only
"Set production as default"                                              <- persists between sessions

Первое подключение, добавленное в группу, автоматически становится подключением по умолчанию. Переключение подключений меняет только активное для текущей сессии — после перезапуска вы вернётесь к подключению по умолчанию. Если нужно, чтобы изменение сохранилось, явно задайте новое подключение по умолчанию.

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

Установка

Claude Code

claude mcp add --scope user database -- npx -y @cocaxcode/database-mcp@latest

Claude Desktop

Добавьте в ваш конфигурационный файл (~/Library/Application Support/Claude/claude_desktop_config.json на macOS, %APPDATA%\Claude\claude_desktop_config.json на Windows):

{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["-y", "@cocaxcode/database-mcp@latest"]
    }
  }
}

Добавьте в .cursor/mcp.json или .windsurf/mcp.json в корне вашего проекта:

{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["-y", "@cocaxcode/database-mcp@latest"]
    }
  }
}

Добавьте в .vscode/mcp.json:

{
  "servers": {
    "database": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cocaxcode/database-mcp@latest"]
    }
  }
}

codex mcp add database -- npx -y @cocaxcode/database-mcp@latest

Или добавьте в ~/.codex/config.toml:

[mcp_servers.database]
command = "npx"
args = ["-y", "@cocaxcode/database-mcp@latest"]

Добавьте в ~/.gemini/settings.json:

{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["-y", "@cocaxcode/database-mcp@latest"]
    }
  }
}

Установка драйверов

Установите только те драйверы, которые вам нужны, — они загружаются динамически во время выполнения:

npm install -g postgres       # PostgreSQL (postgres.js)
npm install -g mysql2         # MySQL
npm install -g sql.js         # SQLite (runs in-process, no native bindings)

Примечание: При использовании npx драйверы должны быть установлены глобально. Если вы устанавливаете сервер глобально (npm install -g @cocaxcode/database-mcp), драйверы могут быть локальными или глобальными.

Возможности

Несколько баз данных — один интерфейс

Большинство MCP-серверов для баз данных заставляют вас перенастраивать учётные данные в каждой сессии. Этот — нет. Именованные подключения сохраняются внутри групп: создайте их один раз и пользуйтесь вечно.

Именованные подключения работают как git-ветки. Вы создаёте dev, staging, prod один раз внутри группы, и они всегда там. Переключение мгновенное — одна команда, ноль перенастройки:

"Create a group called my-project and add this directory as scope"
"Create a connection called dev with host localhost, database myapp, user admin in my-project"
"Create a read-only connection called analytics pointing to ./data/metrics.db in my-project"
"Switch to dev"               -> queries go to PostgreSQL
"Switch to analytics"         -> queries go to SQLite
"Duplicate dev as dev-readonly with read-only mode"

Подключения, ограниченные группами, означают, что разные проекты автоматически видят разные базы данных. Работаете над проектом A? Вы видите группу и подключения проекта A. Переключитесь на каталог проекта B — и он подхватит группу проекта B с её собственным подключением по умолчанию. Никакого ручного переключения и взаимных помех между проектами:

"Create a group called frontend with scope /home/user/frontend"
"Create a group called backend with scope /home/user/backend"

Теперь у каждого каталога есть свой изолированный набор подключений.

100% локальные учётные данные. Каждое подключение хранится в виде JSON-файла в ~/.database-mcp/connections/. Пароли никогда не покидают вашу машину. Ничего не отправляется в облако. Ничего не попадает в git. Ваши учётные данные принадлежат вам.

Живое управление. Создавайте, дублируйте, переименовывайте, проверяйте, экспортируйте и переключайте подключения прямо во время разговора. Никакого перезапуска, редактирования конфигурационных файлов и потери контекста.

Встроенная безопасность

Снимки для отката

Каждая мутация сохраняет снимок предыдущего состояния. Отменить можно что угодно.

"Show me available rollbacks"
"Rollback the last delete"
  -> "This will INSERT 47 rows back into orders. Confirm?"
  -> Rows restored via reverse SQL

Интроспекция схемы

Три уровня детализации с фильтрацией по шаблону:

"List all tables"                         -> names only (fast)
"Show me the users table with columns"    -> columns + types + nullable
"Full schema for orders including FKs"    -> columns + foreign keys + indexes
"Tables starting with user"              -> pattern: 'user%'

MCP Resources (db://schema и db://tables/{name}/schema) дают ИИ-агентам автоматический доступ к вашей схеме — ручной SQL не нужен для запросов к нескольким таблицам.

Выполнение запросов с EXPLAIN

"Show me all users"
  -> SELECT * FROM users LIMIT 100         <- auto LIMIT

"Show the execution plan for this query"
  -> EXPLAIN ANALYZE with dialect-specific syntax (PostgreSQL/MySQL/SQLite)

Режимы сжатия (v0.3+)

Результаты SQL часто содержат столбцы TEXT / JSON / HTML, которые могут занимать килобайты на строку. ИИ-агенты платят за каждый байт, попадающий в контекстное окно. execute_query, execute_mutation и explain_query принимают четыре необязательных параметра, которые сокращают 60-95% этих токенов, сохраняя строки и структуру нетронутыми.

Режимы:

• minimal — только rowCount, executionTimeMs, affectedRows и предпросмотр первой строки. Идеально для подтверждения INSERT/UPDATE/DELETE, COUNT-запросов, опроса. Экономит ~90-95% токенов.

• normal (по умолчанию) — полные строки, но каждая ячейка обрезается до max_cell_bytes с маркером …(+NB). Сохраняет структуру таблицы. Экономит ~60-80% токенов на широких строках.

• full — весь результат без изменений. Используйте, когда нужно полное значение каждой ячейки.

Типичная экономия на SELECT * FROM blog_posts LIMIT 100, где content — это ~2KB HTML на строку (~200KB всего):

Для прямого сравнения с сырым psql с измеренными числами см. раздел Нативные альтернативы ниже.

Восстановление полного результата: каждый сжатый ответ содержит call_id. Если позже понадобятся полные ячейки, вызовите inspect_last_query({ call_id }) — без повторного выполнения SQL, сохраняя нагрузку на БД и любые побочные эффекты. Результаты хранятся в кольцевом буфере на 20 слотов и сохраняются в ~/.database-mcp/last-queries/ с TTL 1 час.

// Example: normal (default) response
{
  "call_id": "k3m9a2xp",
  "columns": ["id", "title", "content"],
  "rows": [
    { "id": 1, "title": "Hello", "content": "<h1>Long HTML…(+1847B)" }
  ],
  "rowCount": 1,
  "executionTimeMs": 12,
  "cells_truncated": 1,
  "hint": "1 cell(s) truncated to 500 bytes. Use inspect_last_query({ call_id: \"k3m9a2xp\" }) for full values.",
  "tokens_saved_estimate": 462
}

Нативные альтернативы: реальная стоимость токенов

Как этот MCP сравнивается с нативными вариантами, которые есть у Claude Code, когда database недоступен (Bash + psql, sqlite3, mysql CLI и т. д.).

Кратко: по сравнению с сырым psql, execute_query экономит от 78% до 96% токенов контекста в зависимости от режима, без потери отладочной информации. Измерено на реальном вызове SELECT * FROM blog_posts LIMIT 5 для таблицы PostgreSQL со столбцом content объёмом ~1 KB HTML на строку:

Почему числа в этой таблице отличаются от раздела «Режимы сжатия» выше: здесь приведены данные реального запроса из 5 строк, тогда как предыдущая таблица экстраполирует результат на 100 строк с более тяжёлым содержимым. Тренд и порядок величины совпадают.

Примечания:

• Сырой вывод psql деградирует по мере роста числа строк — для JSONB и длинных TEXT-колонок нет нативного фильтра. Усечение ячеек в MCP сохраняет структуру (количество строк + список колонок), сворачивая тяжёлые ячейки с маркером …(+NB).

• inspect_last_query возвращает полный результат без повторного выполнения SQL. С psql пришлось бы выполнять запрос заново, снова расходуя CPU базы данных и рискуя повторно вызвать побочные эффекты в предложениях RETURNING.

• MCP также добавляет возможности, у которых нет прямого нативного аналога: группы подключений, привязанные к каталогам проектов, автоматические снапшоты отката при мутациях, история запросов, интроспекция схемы через MCP Resources, а также дамп/восстановление.

• Контекст схемы добавляется в конец ответа, когда это уместно (по умолчанию true для normal/full). Отключите с помощью include_schema_context: false, если агенту уже известна схема.

• Каждый зарегистрированный MCP добавляет фиксированные накладные расходы ~300-600 токенов за сессию (блок инструкций + имена инструментов). Типичная точка безубыточности: 1 реальный запрос за сессию.

Дамп и восстановление

Полное резервное копирование базы данных в формате SQL — только структура или структура + данные.

"Dump the database"
  -> Choose: structure only or full
  -> Choose: all tables or specific ones
  -> SQL file saved to .database-mcp/dumps/

"Restore from the last dump"
  -> Lists available dumps, asks for confirmation, executes

Сгенерированный SQL обрабатывает DROP TABLE IF EXISTS, отключение/включение FK и DDL с учётом диалекта.

История запросов

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

"What queries did I run today?"
"Show me only mutations"
"History for the prod connection"

Экспорт и импорт подключений

"Export all connections"                    -> JSON with masked passwords
"Export with secrets included"             -> JSON with real credentials
"Import these connections: { ... }"        -> creates missing connections

Справочник инструментов

33 инструмента в 8 категориях, плюс 2 MCP Resources:

Ресурсы: db://schema · db://tables/{tableName}/schema

Совет: Вам никогда не нужно вызывать эти инструменты напрямую. Просто опишите, что хотите, и ИИ выберет подходящий.

Хранилище

Хранилище намеренно разделено на два местоположения. Это разделение неслучайно и решает реальную проблему: ваши учётные данные принадлежат вам, а история проекта — проекту.

Глобальное: ~/.database-mcp/ — группы, подключения, учётные данные и настройки. Находится в вашем домашнем каталоге. Никогда внутри проекта. Никогда в git. Никогда не передаётся никому, если вы явно не экспортируете.

На проект: {project}/.database-mcp/ — история запросов, снапшоты отката и дампы базы данных. Находится внутри каталога проекта и автоматически добавляется в .gitignore при первой записи.

~/.database-mcp/                          # Global (configurable via DATABASE_MCP_DIR)
├── groups/                               # Connection groups with scopes and defaults
├── connections/                          # Connection configs (credentials, chmod 600)
├── project-conns.json                    # Session-only active connections (cleared on restart)
└── config.json                           # Server config (limits)

{your-project}/.database-mcp/            # Per-project (auto-gitignored)
├── history.json                          # Query history (max 5000)
├── rollbacks.json                        # Pre-mutation snapshots (max 1000)
└── dumps/
    └── {conn}-{timestamp}-{mode}.sql     # Database dumps

Результат: вы можете свободно делиться репозиторием проекта — соавторы получают историю и структуру отката, но ноль учётных данных. Они создают свои собственные подключения и группы локально.

Конфигурация

Настраивается из диалога или через переменные окружения:

"Set max rollbacks to 2000"
"Set max history to 10000"

Приоритет: переменная окружения > сохранённая конфигурация > значение по умолчанию.

Предупреждение: Если вы переопределяете DATABASE_MCP_DIR на путь внутри git-репозитория, добавьте .database-mcp/ в ваш .gitignore, чтобы не запушить учётные данные.

Архитектура

src/
├── index.ts              # Entry point (StdioServerTransport)
├── server.ts             # createServer() factory
├── tools/                # 33 tool handlers (one file per category)
├── resources/            # MCP Resources (schema auto-discovery)
├── services/             # Business logic
│   ├── connection-manager    # Lazy connect, driver caching
│   ├── schema-introspector   # Multi-dialect introspection (3 detail levels)
│   ├── query-executor        # Read/mutation/explain with safety
│   ├── rollback-manager      # Snapshot capture + reverse SQL
│   ├── history-logger        # Per-project query log
│   └── dump-manager          # Dump/restore (SQL generation)
├── drivers/              # Database adapters (postgres, mysql, sqlite)
├── lib/                  # Types, storage, sanitization
└── utils/                # SQL classifier, parser, formatter

• Ноль зависимостей времени выполнения помимо @modelcontextprotocol/sdk и zod

• Строгий TypeScript — без any

• Динамическая загрузка драйверов — import('postgres') / import('mysql2/promise') / import('sql.js') во время выполнения

• < 60 КБ в сборке через tsup

• Фабричный шаблон — createServer(storageDir?, projectDir?) для изолированных тестовых экземпляров

MIT · Создано cocaxcode