QuestDB Web Console MCP Server

QuestDB MCP 服务

一个 MCP 服务，用于将编码 Agent（Claude Code、Codex、Cursor、OpenCode、Gemini CLI）连接到正在运行的 QuestDB Web Console。Agent 可使用相应工具创建 notebook 单元格、运行查询和构建图表。每项操作都会在浏览器中基于你已建立的 QuestDB 会话执行。

设置

快速设置（推荐）

交互式向导会检测已安装的编码 Agent，并将桥接配置写入每个 Agent 的 MCP 配置中：

npx @questdb/mcp-server-questdb setup

向导会引导你完成两个步骤：

1. 选择 Agent：从检测到的 Agent 中多选（Claude Code、Codex、Cursor、OpenCode、Gemini CLI）。
2. 检查设置：可选择覆盖 CONSOLE_ORIGIN 和 MCP_BRIDGE_PORT；按 Enter 保留默认值。

向导会将每个 Agent 的配置固定到运行该向导的桥接版本。你的 QuestDB Web Console 需要特定的桥接版本。如果你使用的是较旧版本的控制台，请运行匹配的版本：npx @questdb/mcp-server-questdb@<version> setup。它写入的配置将启动同一版本。（如果不确定，请先配对；版本不匹配时，系统会告知 Agent 要切换到哪个版本。） 对于早于 0.3.0 的版本，请改用之前的包名： npx @questdb/mcp-bridge@<version> setup。

手动设置

或者，手动将其添加到 MCP 客户端的配置中（例如 ~/.claude/.mcp.json）：

{
  "mcpServers": {
    "questdb": {
      "command": "npx",
      "args": ["-y", "@questdb/mcp-server-questdb"]
    }
  }
}

离线／受限环境安装（无需 npx）

无法运行 npx 的环境（无法访问 npm registry、先审查后引入依赖的策略）可以使用每个受支持版本所附带的独立捆绑包 GitHub Release： 这是一个独立的 .mjs 文件，只需 Node ≥ 22，除连接 Web Console 的本地 WebSocket 外，不会建立任何网络连接。

从桥接版本 0.4.0 起提供独立捆绑包。所有受支持的 QuestDB Web Console 版本都需要 0.4.0 或更高版本的桥接。

从发布页下载捆绑包（mcp-server-questdb-<version>.mjs）和 THIRD_PARTY_NOTICES.txt，然后在设置前将捆绑包移至固定位置——不要从下载目录或临时目录进行配置——并使用该确切路径运行：

node /permanent/absolute/path/mcp-server-questdb-<version>.mjs setup

设置会写入直接启动捆绑包文件的 Agent 配置（无需使用 npx），因此移动或删除该确切路径会导致 MCP 服务无法启动。要切换版本，请将匹配的捆绑包放在当前文件旁边，然后运行 node /permanent/absolute/path/mcp-server-questdb-<new-version>.mjs upgrade；该命令会将 Agent 配置重新指向新文件，同时保留环境变量设置。如果已配置的文件此前被移动，请从其新的绝对路径运行 upgrade。setup 和 upgrade 始终会写入与你运行的二进制文件对应的安装方式：捆绑包会写入文件路径配置；npx 会写入 npx 配置。

环境变量

标签	值	默认值	描述
CONSOLE_ORIGIN	origin URL	http://127.0.0.1:9000	QuestDB Web Console 的 origin。127.0.0.1 和 localhost 可以互换。
MCP_BRIDGE_PORT	1–65535	自动分配	指定后，桥接程序将使用固定端口。首次尝试配对时会绑定该端口；如果端口已被占用，配对会失败并返回 bridge_bind_failed 错误。
LOG_PATH	文件路径	/tmp/questdb-mcp-bridge/<ISO-ts>-<pid>.log	覆盖日志文件位置。
LOG_LEVEL	ERROR / WARN / INFO / DEBUG	INFO	DEBUG 会记录心跳和完整的工具载荷。

命令

MCP 客户端会根据上述配置为你运行桥接程序，因此你很少需要手动调用它。需要时：

命令	描述
npx @questdb/mcp-server-questdb（无参数）	启动桥接程序——与 start 相同。
npx @questdb/mcp-server-questdb start	启动桥接程序。
npx @questdb/mcp-server-questdb setup	交互式配置桥接程序，以供你的编码 Agent 使用。
npx @questdb/mcp-server-questdb --version	输出版本并退出。别名：-v。
npx @questdb/mcp-server-questdb --help	输出此帮助信息并退出。别名：-h。

未知命令会以非零状态码退出，并显示简短错误信息。使用 npx @questdb/[email protected] start 固定版本。（安装到 PATH 后，可执行文件名为 mcp-server-questdb。）

配对

在任何笔记本、图表或 SQL 工具生效之前，浏览器必须先与桥接程序配对。此流程由 Agent 发起。

Agent 需要配对时，会调用 get_pairing_credentials 并向你展示以下两项：

• 一键深层链接——在显示 Web Console 的标签页中打开。
• WebSocket URL + 令牌——如果深层链接未跳转到正确的标签页，请粘贴到 Web Console 底部的 MCP pill 中。

任一方式都会打开同意提示。接受后，Agent 的下一次工具调用即可正常执行。

每次运行桥接程序都会生成新的端口和配对令牌，并且仅保存在内存中。重启后，旧凭据将失效——Agent 下次需要配对时会提供新凭据。

日志

桥接程序会将日志写入 stderr 和日志文件。查看最新日志：

tail -F "$(ls -t /tmp/questdb-mcp-bridge/*.log | head -1)"

默认 INFO 级别：

2026-05-15T12:29:27.142Z [INFO] tool_call: run_query
2026-05-15T12:29:27.318Z [INFO] tool_result: run_query ok
2026-05-15T12:29:28.011Z [ERROR] tool_result: update_cell internal_error timeout after 15000ms

DEBUG 级别（完整载荷作为续行记录）：

2026-05-15T12:29:27.142Z [INFO] tool_call: run_query
2026-05-15T12:29:27.142Z [DEBUG]   args: {"query":"SELECT count() FROM trades"}
2026-05-15T12:29:27.318Z [INFO] tool_result: run_query ok
2026-05-15T12:29:27.318Z [DEBUG]   content: [{"type":"text","text":"..."}]

许可证

Apache-2.0。