OmniSQL MCP

Универсальный MCP-сервер для баз данных — предоставьте AI-ассистентам доступ на чтение и запись к вашим базам данных, используя подключения, уже сохранённые в рабочем пространстве вашего локального DB-клиента (совместимого с DBeaver).

Это форк srthkdev/omnisql-mcp, в который добавлена поддержка SSH-туннелей / jump-хостов. Он не опубликован в npm — соберите его из этого репозитория (см. Установка).

Поддерживаемые базы данных

Встроенная поддержка (прямой драйвер, быстро):

• PostgreSQL (через pg)

• MySQL / MariaDB (через mysql2)

• SQL Server / MSSQL (через mssql)

• SQLite (через CLI sqlite3)

• Trino / Presto (через trino-client)

Совместимые с PostgreSQL (автоматически маршрутизируются через драйвер pg):

• CockroachDB, TimescaleDB, Amazon Redshift, YugabyteDB, AlloyDB, Supabase, Neon, Citus

Другие базы данных: используется внешний CLI, настраиваемый через OMNISQL_CLI_PATH. Результаты зависят от конкретного CLI.

Related MCP server: DBHub

Возможности

• Переиспользует подключения, уже настроенные в рабочем пространстве вашего локального DB-клиента — без дублирования настройки

• Автоматическая поддержка SSH-туннелей / jump-хостов: прозрачное подключение через тот же SSH-туннель и профиль шлюза / jump-хоста, который настроен для подключения (включая цепочки jump-серверов), без отдельной настройки туннеля

• Нативное выполнение запросов для PostgreSQL, MySQL/MariaDB, SQLite, SQL Server, Trino/Presto

• Пул подключений с настраиваемым размером и таймаутами (пулинг неприменим к SQLite или Trino/Presto, которые работают без постоянного подключения на каждый запрос)

• Поддержка транзакций (BEGIN/COMMIT/ROLLBACK)

• Анализ плана выполнения запросов (EXPLAIN)

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

• Режим только для чтения с принудительным SELECT-only для execute_query

• Белый список подключений для ограничения доступа к базам данных

• Фильтрация инструментов для отключения отдельных операций

• Проверка запросов для блокировки опасных операций (DROP DATABASE, TRUNCATE, DELETE/UPDATE без WHERE)

• Экспорт данных в CSV/JSON

• Корректное завершение работы с очисткой пула подключений

Требования

• Node.js 18+

• Локальный DB-клиент (совместимый с DBeaver) с хотя бы одним настроенным подключением

Установка

Этот форк не опубликован в npm — соберите его из исходного кода:

git clone https://github.com/sangameshBB/omnisql-mcp.git
cd omnisql-mcp
npm install
npm run build

Затем свяжите собранный сервер, чтобы команда omnisql-mcp указывала на него:

npm install -g .

Не запускайте npm install -g omnisql-mcp отдельно. Это установит оригинальный пакет из npm-реестра, в котором нет поддержки SSH-туннелей / jump-хостов. Вы должны клонировать этот репозиторий и собрать его локально, а затем выполнить npm install -g . из клонированной папки, как показано выше.

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

Claude Desktop

Добавьте в ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "omnisql": {
      "command": "omnisql-mcp"
    }
  }
}

Claude Code

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

{
  "mcpServers": {
    "omnisql": {
      "command": "omnisql-mcp"
    }
  }
}

Cursor

Добавьте в Cursor Settings > MCP Servers:

{
  "mcpServers": {
    "omnisql": {
      "command": "omnisql-mcp"
    }
  }
}

Без глобальной установки

Если вы не хотите выполнять npm install -g ., укажите MCP-клиенту напрямую на собранную точку входа:

{
  "mcpServers": {
    "omnisql": {
      "command": "node",
      "args": ["/absolute/path/to/omnisql-mcp/dist/index.js"]
    }
  }
}

Переменные окружения

Режим только для чтения

Блокирует все операции записи. Инструмент execute_query разрешает только SELECT, EXPLAIN, SHOW и DESCRIBE. Инструменты транзакций полностью отключены.

{
  "mcpServers": {
    "omnisql": {
      "command": "omnisql-mcp",
      "env": {
        "OMNISQL_READ_ONLY": "true"
      }
    }
  }
}

Белый список подключений

Ограничивает видимые подключения рабочего пространства. Принимает ID подключений или отображаемые имена через запятую:

{
  "mcpServers": {
    "omnisql": {
      "command": "omnisql-mcp",
      "env": {
        "OMNISQL_ALLOWED_CONNECTIONS": "dev-postgres,staging-mysql"
      }
    }
  }
}

Отключение отдельных инструментов

{
  "mcpServers": {
    "omnisql": {
      "command": "omnisql-mcp",
      "env": {
        "OMNISQL_DISABLED_TOOLS": "drop_table,alter_table,write_query"
      }
    }
  }
}

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

Управление подключениями

• list_connections — список всех подключений к базам данных

• get_connection_info — получение сведений о подключении

• test_connection — проверка связи

Операции с данными

• execute_query — выполнение запросов только для чтения (только SELECT, EXPLAIN, SHOW, DESCRIBE)

• write_query — выполнение INSERT/UPDATE/DELETE

• export_data — экспорт в CSV/JSON

Управление схемой

• list_tables — список таблиц и представлений

• get_table_schema — получение структуры таблицы

• create_table — создание таблиц

• alter_table — изменение таблиц

• drop_table — удаление таблиц (требуется подтверждение)

Транзакции

• begin_transaction — начало новой транзакции

• execute_in_transaction — выполнение запроса в рамках транзакции

• commit_transaction — фиксация транзакции

• rollback_transaction — откат транзакции

Анализ запросов

• explain_query — анализ плана выполнения запроса

• compare_schemas — сравнение схем между двумя подключениями

• get_pool_stats — статистика пула подключений

SSH-туннель / Jump-хост

• get_ssh_tunnel_info — просмотр профиля SSH-туннеля / jump-хоста, связанного с подключением (сведения скрыты, без секретов)

Прочее

• get_database_stats — статистика базы данных

• append_insight — сохранение заметок анализа

• list_insights — получение сохранённых заметок

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

• Принудительный режим только для чтения: execute_query принимает только операторы чтения (SELECT, EXPLAIN, SHOW, DESCRIBE, PRAGMA). Операции записи должны использовать write_query.

• Проверка запросов: блокирует DROP DATABASE, DROP SCHEMA, TRUNCATE, DELETE/UPDATE без WHERE, GRANT, REVOKE и операторы управления пользователями.

• Белый список подключений: ограничение доступа к подключениям через OMNISQL_ALLOWED_CONNECTIONS.

• Фильтрация инструментов: отключение любого инструмента через OMNISQL_DISABLED_TOOLS.

• Санация входных данных: ID подключений и SQL-идентификаторы очищаются для предотвращения инъекций.

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

Поддержка форматов рабочего пространства

Поддерживаются оба формата конфигурации, создаваемые DB-клиентами, совместимыми с DBeaver:

• Устаревший: XML-конфигурация в .metadata/.plugins/org.jkiss.dbeaver.core/

• Современный: JSON-конфигурация в General/.dbeaver/

Учётные данные автоматически расшифровываются из credentials-config.json рабочего пространства.

Поддержка SSH-туннелей / jump-хостов

Если для подключения настроен SSH-туннель (сетевой обработчик) в вашем DB-клиенте — включая один или несколько цепочек jump-серверов / шлюзов — каждый нативный запрос, test_connection, транзакция и пул подключений прозрачно маршрутизируются через него. Отдельная настройка туннеля не требуется: сервер открывает локальный проброс порта через ту же цепочку SSH-хопов, которую использовал бы ваш DB-клиент, и подключает нативный драйвер (pg, mysql2, mssql) к этой локальной конечной точке.

• Поддержка аутентификации по паролю, открытому ключу и SSH-агенту для каждого хопа

• Поддержка цепочек jump-серверов (localhost -> jump host(s) -> final SSH host -> database)

• Туннели открываются один раз для каждого подключения и переиспользуются между запросами; закрываются при завершении работы

• Используйте get_ssh_tunnel_info для просмотра профиля туннеля / jump-хоста подключения (хост, порт, тип аутентификации, количество jump-серверов) без раскрытия секретов

• Если пароль или парольную фразу ключа невозможно восстановить из зашифрованного хранилища учётных данных рабочего пространства, задайте OMNISQL_SSH_PASSWORD, OMNISQL_SSH_PASSPHRASE или OMNISQL_SSH_PRIVATE_KEY_PATH в качестве запасного варианта

Поддержка Trino / Presto

Подключения Trino работают через HTTPS/HTTP (базовая аутентификация), используя те же хост/пользователь/пароль, которые уже сохранены для подключения. Несколько замечаний, специфичных для Trino:

• Каталог/схема необязательны. Если для подключения не настроен каталог/схема по умолчанию (обычно при просмотре нескольких каталогов в DBeaver), запросы должны полностью квалифицировать таблицы как catalog.schema.table.

• list_tables и get_table_schema не зависят от каталога по замыслу (через system.jdbc.tables/system.jdbc.columns), поэтому они работают без каталога по умолчанию — но в большом мультикаталожном кластере это сканирует метаданные по всем каталогам, что может быть медленным и возвращать дублирующиеся строки, если одно и то же имя таблицы существует в нескольких каталогах/схемах. Для быстрого и однозначного поиска используйте execute_query с DESCRIBE catalog.schema.table.

• SSH-туннелирование (выше) работает для Trino так же, как и для других драйверов.

• Trino не имеет постоянной модели сессий/транзакций в этом сервере — begin_transaction и пул подключений недоступны для Trino (как и для SQLite).

Разработка

git clone https://github.com/sangameshBB/omnisql-mcp.git
cd omnisql-mcp
npm install
npm run build
npm test
npm run lint

Лицензия

MIT