用途：QuestDB MCP Server 是一个 MCP（Model Context Protocol）服务器，用于把编程类 AI 智能体连接到正在运行的 QuestDB Web Console。连接后，智能体可以创建 notebook 单元格、运行查询并构建图表；每一项操作都在浏览器中、针对用户已经建立的 QuestDB 会话执行。
主要能力：智能体通过该服务器获得三类工具操作：创建 notebook 单元格、运行 SQL 查询、构建图表（图表运行在实时时间序列数据之上）。文档明确其支持连接的编程智能体包括 Claude Code、Codex、Cursor、OpenCode、Gemini CLI。
使用方式（快速安装，推荐）：提供交互式安装向导，会自动检测已安装的编程智能体，并把连接桥写入每个智能体的 MCP 配置。向导分两步：一是选择智能体（从检测到的 Claude Code、Codex、Cursor、OpenCode、Gemini CLI 中多选）；二是查看设置（可选覆盖 CONSOLE_ORIGIN 和 MCP_BRIDGE_PORT，直接回车保留默认值）。向导会把每个智能体的配置固定到运行它的那个桥版本。
版本匹配：QuestDB Web Console 期望特定版本的桥。如果使用较旧的 console，需要运行匹配版本：npx @questdb/mcp-server-questdb@<version> setup，它写入的配置会启动同一版本。不确定时先配对；出现版本不匹配时，智能体会被告知需要切换到哪个版本。对于 0.3.0 之前的版本，应改用旧包名：npx @questdb/mcp-bridge@<version> setup。
手动配置：也可以把服务器手动加入 MCP 客户端配置（例如 ~/.claude/.mcp.json）。
离线/受限安装（无 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 后，需先把打包文件移动到永久位置再运行 setup——不要从下载目录或临时目录配置——并调用该确切路径。Setup 写入的智能体配置会直接启动该打包文件（不涉及 npx），因此移动或删除该确切路径将导致 MCP 服务器无法启动。切换版本时，把匹配的新打包文件放在当前文件旁，运行 node /permanent/absolute/path/mcp-server-questdb-<new-version>.mjs upgrade；它会在保留环境设置的同时把智能体配置重新指向新文件。如果已配置的文件已被移动，从其新的绝对路径运行 upgrade。setup 和 upgrade 总是写入所运行二进制的安装方式：打包文件写入文件路径配置，npx 写入 npx 配置。
环境变量：MCP 客户端会通过上述配置代为运行该桥，因此很少需要手动调用。手动调用时，未知命令会以非零状态退出并给出简短错误。可用 npx @questdb/mcp-server-questdb@0.3.0 start 固定版本；安装到 PATH 后，可执行文件名为 mcp-server-questdb。
配对流程：在任何 notebook/图表/SQL 工具可用之前，浏览器必须与桥配对，流程由智能体驱动。当智能体需要配对时，会调用 get_pairing_credentials 并向用户同时展示：一是一键深链接（在显示 Web Console 的标签页中打开）；二是 WebSocket URL + token（如果深链接没有落到正确的标签页，可粘贴到 Web Console 底部的 MCP pill 中）。任一方式都会进入同意提示，接受后智能体的下一次工具调用即可通过。每次桥运行都会生成新的端口和配对令牌，仅保存在内存中；重启后旧凭据失效，智能体在下次需要配对时会给出新的凭据。
日志：桥会写入 stderr 和日志文件。默认 INFO 级别；设为 DEBUG 可看到完整负载（以续行形式输出）。
适用场景：需要让编程智能体在已运行的 QuestDB Web Console 上操作时间序列数据时，例如通过 notebook 单元格探索数据、执行 SQL 查询、基于实时数据构建图表。
限制：浏览器必须先完成与桥的配对，工具才能使用；桥版本需与 QuestDB Web Console 版本匹配（0.3.0 之前需用旧包名，独立打包文件要求桥版本 0.4.0+ 且 console 版本也要求 0.4.0+）；独立打包文件仅需 Node ≥ 22，除本地 WebSocket 外不建立网络连接，但移动打包文件路径会导致服务器无法启动；配对凭据仅存内存，重启后失效。关于收费、价格、平台支持等更多信息，资料中暂未提供。
