QuestDB Web Console MCP Server

QuestDB MCP サーバー

コーディングエージェント（Claude Code、Codex、Cursor、OpenCode、Gemini CLI）を、実行中の QuestDB Web Console に接続する MCP サーバーです。エージェントには、ノートブックのセルの作成、クエリの実行、チャートの作成を行うツールが提供されます。すべての操作は、すでに確立されている QuestDB セッションを使ってブラウザー上で実行されます。

セットアップ

クイックセットアップ（推奨）

対話型ウィザードがインストール済みのコーディングエージェントを検出し、それぞれの MCP 設定にブリッジを書き込みます。

npx @questdb/mcp-server-questdb setup

ウィザードは次の 2 つの手順を案内します。

1. エージェントの選択：検出されたエージェント（Claude Code、Codex、Cursor、OpenCode、Gemini CLI）から複数選択します。
2. 設定の確認：必要に応じて CONSOLE_ORIGIN と MCP_BRIDGE_PORT を上書きします。デフォルトのままにするには Enter キーを押します。

ウィザードは、実行に使用したブリッジのバージョンを各エージェントの設定に固定します。QuestDB Web Console では、特定のブリッジバージョンが必要です。古いコンソールをお使いの場合は、対応するバージョンを実行してください：npx @questdb/mcp-server-questdb@<version> setup。書き込まれる設定では、同じバージョンが起動します。（不明な場合は、まず接続してください。バージョンが一致しない場合、エージェントに切り替えるべきバージョンが通知されます。） 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 レジストリにアクセスできない環境、検証後にベンダー提供のソフトウェアを導入するポリシーがある環境）では、サポート対象の各バージョンの GitHub リリースに添付されているスタンドアロンバンドルを使用できます。Node ≥ 22 だけで動作する、自己完結型の .mjs ファイル 1 つで、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

セットアップでは、バンドルファイルを直接起動するエージェント設定が書き込まれます（npx は使用しません）。そのため、そのファイルを移動または削除すると、MCP サーバーが起動できなくなります。バージョンを切り替えるには、対応するバンドルを現在のファイルの隣に置き、node /permanent/absolute/path/mcp-server-questdb-<new-version>.mjs upgrade を実行します。環境変数の設定は維持したまま、エージェント設定の参照先を新しいファイルに変更します。設定済みのファイルをすでに移動した場合は、新しい絶対パスから upgrade を実行してください。setup と upgrade は、実行するバイナリのインストール形式に合わせて常に設定を書き込みます。バンドルの場合はファイルパスの設定が、npx の場合は npx の設定が書き込まれます。

環境変数

ラベル	値	デフォルト値	説明
CONSOLE_ORIGIN	オリジン URL	http://127.0.0.1:9000	QuestDB Web Console のオリジンです。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	コーディングエージェント用にブリッジを対話形式で設定します。
npx @questdb/mcp-server-questdb --version	バージョンを表示して終了します。別名：-v。
npx @questdb/mcp-server-questdb --help	このヘルプを表示して終了します。別名：-h。

不明なコマンドを指定すると、短いエラーを表示してゼロ以外の終了コードで終了します。バージョンを固定するには、npx @questdb/[email protected] start を実行します。（PATH にインストールした場合、実行ファイル名は mcp-server-questdb です。）

ペアリング

ノートブック／チャート／SQL ツールを使う前に、ブラウザーをブリッジとペアリングする必要があります。この手順はエージェントが進めます。

エージェントがペアリングを必要とすると、get_pairing_credentials を呼び出し、次の両方を表示します。

• ワンクリックで開けるディープリンク — Web Console を表示しているタブで開きます。
• WebSocket URL とトークン — ディープリンクで正しいタブが開かない場合は、Web Console 下部の MCP pill に貼り付けます。

どちらの方法でも同意を求める画面が表示されます。同意すると、エージェントによる次のツール呼び出しが実行されます。

ブリッジを実行するたびに、新しいポートとペアリングトークンが生成され、メモリ内にのみ保持されます。再起動すると古い認証情報は使えなくなり、次回ペアリングが必要になったときに、エージェントが新しい認証情報を表示します。

ログ

ブリッジは標準エラー出力とログファイルに書き込みます。最新のログを追跡するには、次のようにします。

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。