`@questdb/mcp-server-questdb`

Formerly published as @questdb/mcp-bridge. Every release from 0.3.0 on is published under both names, so existing configs keep working. On an old install, run npx @questdb/mcp-bridge upgrade once — it migrates your agent configs to the new name.

An MCP server that connects coding agents (Claude Code, Codex, Cursor, OpenCode …) to a running QuestDB Web Console. The agent gets tools to create notebook cells, run queries, and build charts. Every action executes in the browser against your already-established QuestDB session.

Setup

Quick setup (recommended)

The interactive wizard detects your installed coding agents and writes the bridge into each one's MCP config:

npx @questdb/mcp-server-questdb setup

It walks you through two steps:

Pick agents: multi-select from the ones it detects (Claude Code, Codex, Cursor, OpenCode, Gemini CLI).
Review settings: optionally override CONSOLE_ORIGIN and MCP_BRIDGE_PORT; press Enter to keep the defaults.

The wizard pins each agent's config to the bridge version that ran it. Your QuestDB Web Console expects a specific bridge version. If you're on an older console, run the matching version: npx @questdb/mcp-server-questdb@<version> setup. The config it writes will launch that same version. (When unsure, pair first; on a version mismatch the agent is told which version to switch to.)

Manual setup

Or add it to your MCP client's config by hand (e.g. ~/.claude/.mcp.json):

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

Environment variables

Label	Value	Default Value	Description
`CONSOLE_ORIGIN`	origin URL	`http://127.0.0.1:9000`	QuestDB Web Console origin. `127.0.0.1` and `localhost` are interchangeable.
`MCP_BRIDGE_PORT`	`1`–`65535`	auto-allocated	When specified, the bridge uses a fixed port. The port is bound on the first pairing attempt, pairing fails with a `bridge_bind_failed` error if the port is taken.
`LOG_PATH`	file path	`/tmp/questdb-mcp-bridge/<ISO-ts>-<pid>.log`	Override the log file location.
`LOG_LEVEL`	`ERROR` / `WARN` / `INFO` / `DEBUG`	`INFO`	`DEBUG` adds heartbeats and full tool payloads.

Commands

Your MCP client runs the bridge for you via the config above, so you rarely invoke it by hand. When you do:

Command	Description
`npx @questdb/mcp-server-questdb` (no args)	Start the bridge — same as `start`.
`npx @questdb/mcp-server-questdb start`	Start the bridge.
`npx @questdb/mcp-server-questdb setup`	Interactively configure the bridge for your coding agents.
`npx @questdb/mcp-server-questdb --version`	Print the version and exit. Alias: `-v`.
`npx @questdb/mcp-server-questdb --help`	Print this help and exit. Alias: `-h`.

An unknown command exits non-zero with a short error. Pin a version with npx @questdb/mcp-server-questdb@0.3.0 start. (Installed on your PATH, the executable is named mcp-server-questdb.)

Pairing

Before any notebook / chart / SQL tool works, your browser has to pair with the bridge. The agent drives the flow.

When the agent needs to pair, it calls get_pairing_credentials and shows you both:

A one-click deep link — open it in the tab showing your Web Console.
A WebSocket URL + token — paste into the MCP pill at the bottom of the Web Console if the deep link doesn't land in the right tab.

Either path lands you on a consent prompt. Accept it and the agent's next tool call goes through.

Each bridge run generates a fresh port and pairing token, held only in memory. On restart the old credentials stop working — the agent will surface new ones the next time it needs to pair.

Logs

The bridge writes to stderr and to a log file. Tail the newest:

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

At default 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

At DEBUG (full payloads as continuation lines):

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":"..."}]

License

Apache-2.0.

QuestDB

Documentation

@questdb/mcp-server-questdb