DataOmni icon DataOmni v1.1.0
EN GitHub

只读 MCP 服务配置指南

让 Claude Code、Codex、Cursor、Windsurf、Copilot、Gemini CLI 或 Claude Desktop 直接安全读取你配好的关系库与四大 NoSQL 工作区——配置文件零密码、写语句硬拦截、生产库彻底隐身。

三步开启只读 MCP 服务 #

dataomni mcp 直接内置于桌面客户端同一个可执行文件中,不起界面窗口,通过标准输入输出(stdio)提供原生的 MCP 协议服务。由于与桌面界面共享同一代码身份,AI 工具可直接复用已配好的 SSH 跳板机、TLS 证书与系统钥匙串口令,全程无需在任何 JSON 配置里粘贴数据库密码。

  1. 将连接密码存入系统钥匙串

    在 DataOmni 中编辑目标连接,确保勾选「将密码保存到系统凭据库」。MCP 作为独立子进程运行,无法读取仅在单次会话内存里输入的临时密码。

  2. 将非生产连接设为「只读」Agent 访问

    确认连接环境为「开发 / 测试 / 预发」,把「命令行与 Agent 访问」改为「只读」并保存。应用会用连接口令与端点指纹计算 HMAC-SHA256 开放凭证(<id>#agent)写入系统钥匙串。

  3. 在你的 AI 编程工具中注册服务

    点选下方你正在使用的 AI 工具,一键复制对应的注册命令或 mcpServers 配置片段。

dataomni mcp 与 dataomni cli PROD HIDDEN
标准 stdio MCP 协议,点选对应工具即可复制接入配置:
claude mcp add dataomni -- /Applications/DataOmni.app/Contents/MacOS/dataomni mcp
各平台 dataomni 可执行文件路径
平台 可执行文件路径 启动参数
macOS /Applications/DataOmni.app/Contents/MacOS/dataomni mcp
Linux(.deb / .rpm) /usr/bin/dataomni mcp
Windows(NSIS / MSI) %LOCALAPPDATA%\DataOmni\dataomni.exe 或 C:\Program Files\DataOmni\dataomni.exe mcp

生产库物理隐身与双重只读防线 #

生产环境(PROD)连接物理不可见,而非仅仅报错拦截

环境设为「生产」的连接在界面上强制锁定关闭 Agent 访问、不签发钥匙串凭证、不出现在 connections 列表里;即便按名字强行调用也直接返回 not_found。

  • 防篡改钥匙串开放凭证:即便本地进程直接手工修改磁盘上的 connections.json 把生产库改成开发库或打开只读开关,也会因算不出钥匙串口令对应的 HMAC-SHA256 凭证而被当场忽略。
  • 改配置即时生效(免重启服务):dataomni mcp 不在内存里缓存权限或口令;在 DataOmni 界面里关掉某个连接的访问,AI 工具下一次调用立刻看不见它。
  • 词法白名单 + 数据库只读事务双保险:每次只收单条读语句(SELECT、无嵌套写的 WITH、SHOW、DESCRIBE、不带 ANALYZE 的 EXPLAIN、VALUES、TABLE),并在数据库级只读事务或只读句柄(含锁死 DuckDB 外部文件访问)内执行,最后一律 ROLLBACK。
  • 隔离宿主机文件系统:MCP 工具表刻意剔除了 export、backup 与 csv-preview,防止原本不能跑 shell 的客户端借道读写用户磁盘上的任意文件。
  • 脱敏调用留痕:每次工具调用都在日志目录的 dataomni-cli.log 写入时间、连接名、工具名、首关键字、长度与 SHA-256 摘要、结果、行数及耗时,绝不记录可能含敏感数据的语句原文。

纵深防御建议:为 Agent 搭配只读数据库账号

数据库的只读事务无法拦截高权限账号自带的非改表管理函数(如 PostgreSQL 超级用户的 pg_terminate_backend 或 MySQL 的 get_lock())。建议同时在服务端使用最小权限只读账号。

内置的 11 个只读 MCP 工具 #

所有工具在 tools/list 中均声明 readOnlyHint: true,回包统一采用顶层 "schema": 1 的 JSON(dictionary 直接返回适合喂给大模型的整库 Markdown 数据字典)。多余未知字段或以 -- 开头的位置参数均按 usage 错误拦截。

dataomni mcp 工具与入参速查
工具名 入参 作用与输出
connections 无 列出已开放给 Agent 的非生产连接(不含口令与私钥路径)。
dictionary connection 导出整库 Markdown 数据字典(表、列、类型、主外键)——建议让 Agent 写 SQL 前先调它。
schema connection, table? 列出整库表与视图,或指定单表的列、索引与外键结构。
ddl connection, table 读取数据库自身的原始建表定义(SHOW CREATE TABLE、DBMS_METADATA、sqlite_master 等)。
query connection, sql, limit?, timeout_seconds? 执行单条只读 SQL(默认最多 200 行,上限 10000 行,超限标记 truncated: true)。
explain connection, sql 获取估算执行计划(不带 ANALYZE,不实际执行语句)。
test connection 测试连接可用性;失败时附带 DNS 解析与端口连通性诊断。
mongo connection, action, ... MongoDB 只读操作:collections、find、count、aggregate(拒绝 $out / $merge)、explain、structure。
redis connection, action, ... Redis 只读操作:keyspaces、scan、get,以及经服务端 COMMAND INFO 确认为 readonly 的 command。
neo4j connection, action, ... Neo4j 只读 Cypher:labels 与 run(先经 EXPLAIN 确认类型为 r,再走只读路由事务)。
es connection, action, ... Elasticsearch / OpenSearch 只读查询:indices 与按路径段白名单校验的 GET/HEAD 及搜索类 POST(_search、_count、_msearch)。

接入常见问题排错 #

MCP 常见现象与解决办法
现象 原因与处理方式
connections 返回空数组,或查库报找不到连接 该连接处于「生产」环境、「命令行与 Agent 访问」仍为关闭,或只手工改了 JSON 未经界面保存签发凭证。请在 DataOmni 编辑连接设为「只读」并保存。
macOS 首次调用一直等待无响应 系统钥匙串授权弹窗正等在桌面后方。切过去输入开机密码并点击「始终允许」,MCP 进程会继续完成本次调用而不退出。
SQL Server 连接无法开启 Agent 访问 SQL Server 缺少会话级只读事务兜底机制,当前版本刻意不在 CLI / MCP 开放 SQL Server。