MCP 接入 · OpsxDB 文档

把 Cursor、Claude Code、VS Code 等 AI 客户端接到 OpsxDB，即可用自然语言查看结构、查询白名单内的库，并与侧栏 Agent 共用同一套工具与安全策略。

什么是 MCP？

MCP（Model Context Protocol）让 AI 客户端调用本机工具。OpsxDB MCP 读取桌面已保存的连接（~/.opsxdb/connections.json），权限由 ~/.opsxdb/mcp.json 统一约束。

AI 助手 → opsxdb-mcp (stdio) → aitools Runtime → 你的数据库
                                    ↘ 审计 ~/.opsxdb/logs/mcp-audit.jsonl

安装

1. Node 启动器（npm）

npm install -g @rlwj-lab/opsxdb-mcp@latest
# 或一次性
npx -y @rlwj-lab/opsxdb-mcp

2. Go 二进制（必需）

npm 包只是启动器，真正的 MCP 服务是 Go 二进制：

cd server && go build -o ../bin/opsxdb-mcp ./cmd/opsxdb-mcp
export OPSXDB_MCP_BIN=/绝对路径/opsxdb/bin/opsxdb-mcp

也可把该二进制放到 PATH（需排在 npm shim 之前）。

3. 桌面设置

打开 设置 → MCP：

查看 Node / npm / 包版本 / Go 二进制是否就绪
复制安装命令与各客户端配置片段
查看读写权限，并勾选允许访问的连接；新配置默认允许读写和危险 SQL

配置 AI 客户端

以 Cursor 为例（~/.cursor/mcp.json 或项目 .cursor/mcp.json）：

{
  "mcpServers": {
    "opsxdb": {
      "command": "npx",
      "args": ["-y", "@rlwj-lab/opsxdb-mcp"],
      "env": {
        "OPSXDB_MCP_BIN": "/绝对路径/opsxdb/bin/opsxdb-mcp"
      }
    }
  }
}

Claude Code 使用项目根目录 .mcp.json（结构相同）。VS Code / Windsurf / Codex / Claude Desktop 的片段可在 设置 → MCP 中按 Tab 复制。

GUI 客户端不一定继承 shell 的 PATH；请使用 OPSXDB_MCP_BIN 绝对路径，不要只写 opsxdb-mcp 或 ~。

安全策略

项	说明
默认读写	新配置使用 `mode=read_write`；Agent 每次写入前显示确认弹框
危险 SQL	新配置默认 `allow_dangerous=true`，DROP/TRUNCATE/ALTER/无 WHERE 更新删除等仍须确认
旧配置	沿用已保存的权限；设置中选择「使用默认权限」可启用读写与危险 SQL
连接白名单	`allowed_connection_ids`；空=拒绝全部
审计	`~/.opsxdb/logs/mcp-audit.jsonl`（含 tool、connection_id、run_id）

外部客户端若在 read_write 下自行传 confirm_danger，视为操作者授权；桌面侧栏 Agent 不会让模型静默带确认令牌。
保存白名单或权限后，外部 MCP 进程在下一次工具调用时读取新策略，无需重启桌面或 AI 客户端；策略文件读取失败时该次调用会被拒绝。

工具列表

工具	说明
`opsxdb_list_connections`	白名单内连接
`opsxdb_list_databases`	库列表
`opsxdb_list_tables`	表/视图
`opsxdb_describe_table`	列定义
`opsxdb_get_schema_context`	紧凑 schema 文本
`opsxdb_execute_query`	SQL（写入需确认，查询有行数上限）
`opsxdb_execute_redis_command`	Redis（写入需确认；FLUSH*/KEYS 永拒）

侧栏 Ask | Agent

Ask：生成/解释/优化，不调库
Agent：多轮调用与 MCP 同源工具；支持 SSE 步骤时间线、「插入编辑器」「在结果区打开」

详见 AI 助手。

开始使用

在 AI 客户端中试：

「列出我的数据库连接」
「demo 库有哪些表」
「查看 users 表结构并查前 5 行」

系统要求

Node.js 18+（若用 npm/npx 启动器）
已安装 OpsxDB 桌面端并至少保存一个连接
已构建 opsxdb-mcp Go 二进制
在设置 → MCP 勾选连接白名单