OmniSQL MCP

通用数据库 MCP 服务器 — 利用本地数据库客户端工作区（兼容 DBeaver）中已保存的连接，为 AI 助手提供数据库的读写访问权限。

这是 srthkdev/omnisql-mcp 的一个分支，增加了 SSH 隧道 / 跳板机支持。它未发布到 npm — 请从本仓库构建（参见安装）。

数据库支持

原生支持（直接驱动，速度快）：

• PostgreSQL（通过 pg）

• MySQL / MariaDB（通过 mysql2）

• SQL Server / MSSQL（通过 mssql）

• SQLite（通过 sqlite3 CLI）

• Trino / Presto（通过 trino-client）

兼容 Postgres（自动通过 pg 驱动路由）：

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

其他数据库：回退到通过 OMNISQL_CLI_PATH 配置的外部 CLI。结果因 CLI 而异。

Related MCP server: DBHub

功能特性

• 复用本地数据库客户端工作区中已配置的连接 — 无需重复设置

• 自动 SSH 隧道 / 跳板机支持：透明地通过连接上配置的同一 SSH 隧道和网关/跳板机配置进行连接（包括链式跳板服务器），无需单独设置隧道

• 为 PostgreSQL、MySQL/MariaDB、SQLite、SQL Server、Trino/Presto 提供原生查询执行

• 连接池，可配置池大小和超时时间（连接池不适用于 SQLite 或 Trino/Presto，它们每次查询都是无连接的）

• 事务支持（BEGIN/COMMIT/ROLLBACK）

• 查询执行计划分析（EXPLAIN）

• 连接之间的模式比较，并生成迁移脚本

• 只读模式，在 execute_query 上强制仅允许 SELECT

• 连接白名单，限制可访问的数据库

• 工具过滤，可禁用特定操作

• 查询验证，阻止危险操作（DROP DATABASE、TRUNCATE、无 WHERE 的 DELETE/UPDATE）

• 数据导出为 CSV/JSON

• 优雅关闭，并清理连接池

环境要求

• Node.js 18+

• 本地数据库客户端（兼容 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 隧道 / 跳板机支持。你必须克隆本仓库并在本地构建，然后按照上面的说明在克隆的文件夹内运行 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 设置 > MCP 服务器：

{
  "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 隧道 / 跳板机

• get_ssh_tunnel_info - 检查与连接关联的 SSH 隧道 / 跳板机配置（已脱敏，不含机密信息）

其他

• get_database_stats - 数据库统计信息

• append_insight - 存储分析笔记

• list_insights - 检索已存储的笔记

安全

• 只读强制：execute_query 仅接受只读语句（SELECT、EXPLAIN、SHOW、DESCRIBE、PRAGMA）。写操作必须使用 write_query。

• 查询验证：阻止 DROP DATABASE、DROP SCHEMA、TRUNCATE、无 WHERE 的 DELETE/UPDATE、GRANT、REVOKE 以及用户管理语句。

• 连接白名单：通过 OMNISQL_ALLOWED_CONNECTIONS 限制暴露哪些连接。

• 工具过滤：通过 OMNISQL_DISABLED_TOOLS 禁用任何工具。

• 输入清理：连接 ID 和 SQL 标识符经过清理以防止注入。

• 建议：在生产环境中，还应使用数据库级别的只读用户进行纵深防御。

工作区格式支持

支持兼容 DBeaver 的数据库客户端写入的两种配置格式：

• 旧版：.metadata/.plugins/org.jkiss.dbeaver.core/ 中的 XML 配置

• 新版：General/.dbeaver/ 中的 JSON 配置

凭据会自动从工作区的 credentials-config.json 中解密。

SSH 隧道 / 跳板机支持

如果连接在数据库客户端中配置了 SSH 隧道（网络处理器）— 包括一个或多个链式跳板服务器 / 网关主机 — 那么每个原生查询、test_connection、事务和池化连接都会透明地通过它路由。无需单独设置隧道：服务器会通过数据库客户端将使用的同一 SSH 跳转链打开本地端口转发，并将原生驱动（pg、mysql2、mssql）连接到该本地端点。

• 支持每跳的密码、公钥和 SSH agent 认证

• 支持链式跳板服务器（localhost -> jump host(s) -> final SSH host -> database）

• 隧道按连接打开一次，并在查询之间复用；关闭时释放

• 使用 get_ssh_tunnel_info 检查连接的隧道/跳板机配置（主机、端口、认证类型、跳板服务器数量），不会暴露任何机密信息

• 如果无法从工作区的加密凭据存储中恢复密码或密钥口令，请设置 OMNISQL_SSH_PASSWORD、OMNISQL_SSH_PASSPHRASE 或 OMNISQL_SSH_PRIVATE_KEY_PATH 作为备用

Trino / Presto 支持

Trino 连接通过 HTTPS/HTTP（基本认证）工作，使用连接已保存的相同主机/用户/密码。几点 Trino 特有的说明：

• Catalog/schema 是可选的。 如果连接未配置默认 catalog/schema（在 DBeaver 中浏览多个 catalog 时很常见），查询必须使用 catalog.schema.table 格式完全限定表名。

• list_tables 和 get_table_schema 在设计上是与 catalog 无关的（通过 system.jdbc.tables/system.jdbc.columns），因此它们在没有默认 catalog 的情况下也能工作 — 但在大型多 catalog 集群上，这会扫描每个 catalog 的元数据，可能很慢，并且如果同一个表名存在于多个 catalog/schema 中，可能会返回重复行。如需快速、无歧义的查找，请改用带 DESCRIBE catalog.schema.table 的 execute_query。

• 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