IoTDB MCP Server

IoTDB MCP サーバー

英語 | 中文

概要

IoTDB を通じてデータベースとのやり取りとビジネスインテリジェンス機能を提供する、Model Context Protocol（MCP）サーバーの実装です。このサーバーでは、異なる SQL 方言（ツリーモデルとテーブルモデル）を使用して、SQL クエリを実行し、IoTDB とやり取りできます。

コンポーネント

リソース

このサーバーはリソースを公開しません。

プロンプト

このサーバーはプロンプトを提供しません。

権限モデル

IoTDB MCP の権限は、デフォルトでは推奨事項として扱われます。サーバーは SQL アクションに必要な権限、リスクレベル、確認パラメーターを報告し、ユーザーの承認はホストのエージェントシステムが担います。ツールを利用できる場合は、DDL／DML または破壊的な SQL を実行する前に inspect_sql_permission を使用してください。

長時間稼働するホスト型エージェントでは、IOTDB_SQL_DRIVER_MODE=full や TIMESEEK_MCP_PERMISSION_ENFORCEMENT=advisory などの環境変数を指定して、すべての権限を許可するデフォルト設定にできます。MCP サーバー自体で許可されていない操作を確実にブロックする場合にのみ、TIMESEEK_MCP_PERMISSION_ENFORCEMENT=strict を設定してください。

セッションポリシーの変更は、起動時に固定されるデプロイポリシー（プロセス環境変数 > MCP 設定 > デフォルト値）の範囲内に制限されます。範囲を狭める変更はすぐに適用されます。デフォルトでは、上限の範囲内であっても、範囲を広げるには管理者による帯域外の承認が必要です。IOTDB_SESSION_POLICY_APPROVAL_MODE=allow を指定すると、承認なしで上限の範囲内での拡張が明示的に許可されます。どちらの設定でも、ツールによる適用方式の切り替え、SQL 分類プレフィックスの変更、デプロイ上限の変更は許可されません。リセットと置換にも同じルールが適用されます。設定、承認コマンド、必要なホストの隔離については、セッションポリシーの管理を参照してください。

ツール

このサーバーは、IoTDB のツリーモデルとテーブルモデルそれぞれに異なるツールを提供します。「IOTDB_SQL_DIALECT」設定に「tree」または「table」を指定して選択できます。

方言ごとの識別子の扱い：

• ツリー方言：
  • FROM の対象には、明示的な root... パスを指定します。
  • 射影式では通常、完全な root... パスではなく測定値名を使用します。
  • IOTDB_DATABASE は接続／セッションのヒントとしてのみ使用されます。ツリー SQL では引き続き明示的なルートパスが必要です。
• テーブル方言：
  • FROM の対象には、現在のデータベース内のテーブル名を指定します。
  • 射影式では列名を使用します。

ツリーモデル

• metadata_query
  • データベースからメタデータを読み取るために、SHOW／COUNT クエリを実行します
  • 入力：
    • query_sql (string)：実行する SHOW／COUNT SQL クエリ
  • サポートされるクエリの種類：
    • SHOW DATABASES [path]
    • SHOW TIMESERIES [path]
    • SHOW CHILD PATHS [path]
    • SHOW CHILD NODES [path]
    • SHOW DEVICES [path]
    • COUNT TIMESERIES [path]
    • COUNT NODES [path]
    • COUNT DEVICES [path]
  • 戻り値：クエリ結果（オブジェクトの配列）
• select_query
  • データベースからデータを読み取るために、SELECT クエリを実行します
  • 入力：
    • query_sql (string)：実行する SELECT SQL クエリ（TREE 方言を使用。時刻は ISO 8601 形式。例：2017-11-01T00:08:00.000）
  • サポートされる関数：
    • SUM、COUNT、MAX_VALUE、MIN_VALUE、AVG、VARIANCE、MAX_TIME、MIN_TIME など
  • 戻り値：クエリ結果（オブジェクトの配列）
• sql_executor_batch
  • 複数の読み取り専用 SQL 文を並列実行し、それぞれの結果を ResultStore に保存します
  • 入力：
    • sqls (array)：個別の SQL 文、または
    • sql_template + param_sets：パラメーターオブジェクトを使用する、繰り返し実行用の SQL テンプレート
    • max_concurrency (integer)：同時実行文数の上限。デフォルトは 4
    • worker_pool_size (integer)：スレッドワーカープールのサイズ。デフォルトは同時実行数に従い、IOTDB_SQL_EXECUTOR_BATCH_MAX_WORKER_POOL_SIZE（デフォルトは 16）を上限とします
    • per_item_timeout_ms (integer)：文ごとの待機タイムアウト。デフォルトは 60000
    • batch_timeout_ms (integer)：バッチ全体の待機タイムアウト。デフォルトは 300000
    • max_result_rows_per_item / max_result_bytes_per_item：文ごとの結果クォータ。デフォルトは 10000 行、16 MiB
    • max_batch_result_rows / max_batch_result_bytes：バッチ全体の結果クォータ。デフォルトは 100000 行、64 MiB
  • テンプレートのプレースホルダー：
    • SQL リテラルには {{name}}、IoTDB パスには {{name:path}}、SQL 識別子には {{name:identifier}} を使用します
  • 戻り値：バッチの概要に加え、各文の result_id、行数、プレビュー行、ページングメタデータ
• read_result_pages
  • 1 回の MCP 呼び出しで複数の ResultStore ページを読み取ります
  • 入力：
    • pages (array)：result_id と、任意の cursor、offset、limit、owner_session_id を含むページリクエストオブジェクト
    • default_limit (integer)：limit が指定されていない項目に適用するデフォルトのページサイズ
    • max_pages / max_total_rows：呼び出しごとのクォータ。デフォルトは 32 ページ、10000 行
    • continue_on_error (boolean)：中断せずに項目ごとのエラーを返すかどうか。デフォルトは true
  • 戻り値：バッチページの概要に加え、各ページの行、カーソル、エラー
• export_query
  • クエリを実行し、結果を CSV または Excel ファイルにエクスポートします
  • 入力：
    • query_sql (string)：実行する SQL クエリ（TREE 方言を使用）
    • format (string)：エクスポート形式。"csv" または "excel"（デフォルト："csv"）
    • filename (string)：エクスポートするファイルの任意のファイル名。指定しない場合は、一意のファイル名が生成されます
  • 戻り値：エクスポートしたファイルの情報とデータのプレビュー（最大 10 行）
• model_inference
  • AINode の CALL INFERENCE(...) SQL を実行し、結果セットを返します
  • 入力：
    • inference_sql (string)：CALL INFERENCE で始まる単一の Tree 方言 SQL 文
  • 実行前に、モデル ID、引用符で囲まれた入力 SELECT SQL、明示的に指定されたワイルドカード以外の列、およびサポート対象のパラメーター（generateTime、outputLength）を検証します
  • 権限メタデータ：モデル管理は、助言的な MCP ポリシーレイヤーを通じて報告されます。厳格モードでは、IOTDB_ENABLE_MODEL_MANAGEMENT=true と IOTDB_MODEL_ALLOWED_USERS が適用されます
• prepare_model_inference_request
  • 構造化フィールドから AINode の CALL INFERENCE(...) SQL を作成し、検証します
  • 入力：
    • model_id (string)：登録済み AINode モデル ID
    • input_sql (string)：モデル入力として使用する、範囲が限定された Tree 方言の SELECT クエリ
    • output_length (int)：予測の出力長（デフォルト：96）
    • generate_time (bool)：Time 列を要求するかどうか（デフォルト：false）

UDF ツール

• list_udf_functions
  • 選択した IoTDB ターゲットに対して SHOW FUNCTIONS を実行します。
• prepare_udf_query
  • 構造化された入力から読み取り専用の UDF SELECT を構築します。
  • ツリー形式：SELECT UDF(measurement, "k"="v") FROM root.sg.d1 ...
  • テーブル形式：SELECT UDF(column, "k"="v") FROM table ...
• execute_udf_query
  • 検証済みの UDF クエリを実行し、ResultStore によるプレビューを返します。
• export_udf_query
  • 検証済みの UDF クエリを実行し、結果セットを CSV または Excel にエクスポートします。

UDF ツールでは、式およびフィルター句内のセミコロン、SQL コメント、DDL／DML キーワードは使用できません。 これらのツールは、データ品質、プロファイリング、修復計画、異常スコアリングなどの読み取り専用 UDF 呼び出しを目的としています。

テーブルモデル

クエリツール

• read_query
  • データベースからデータを読み取るために SELECT クエリを実行します
  • 入力：
    • query_sql （文字列）：実行する SELECT SQL クエリ（TABLE 方言を使用。時刻は ISO 8601 形式。例：2017-11-01T00:08:00.000）
  • 戻り値：オブジェクトの配列としてのクエリ結果

スキーマツール

• list_tables

  • データベース内のすべてのテーブルの一覧を取得します
  • 入力は不要です
  • 戻り値：テーブル名の配列

• describe_table

  • 特定のテーブルのスキーマ情報を表示します
  • 入力：
    • table_name （文字列）：詳細を表示するテーブルの名前
  • 戻り値：名前と型を含む列定義の配列

• export_table_query

  • クエリを実行し、結果を CSV または Excel ファイルにエクスポートします
  • 入力：
    • query_sql （文字列）：実行する SQL クエリ（TABLE 方言を使用）
    • format （文字列）：エクスポート形式。"csv" または "excel"（デフォルト："csv"）
    • filename （文字列）：エクスポートするファイルの任意のファイル名。指定しない場合、一意のファイル名が生成されます。
  • 戻り値：エクスポートしたファイルの情報と、データのプレビュー（最大 10 行）

設定オプション

IoTDB MCP サーバーは、環境変数またはコマンドライン引数で設定できる以下のオプションをサポートしています。

オプション	環境変数	デフォルト値	説明
--host	IOTDB_HOST	127.0.0.1	IoTDB のホストアドレス
--port	IOTDB_PORT	6667	IoTDB のポート
--user	IOTDB_USER	root	IoTDB のユーザー名
--password	IOTDB_PASSWORD	empty	IoTDB のパスワード
--database	IOTDB_DATABASE	test	テーブル方言：現在のデータベース名。ツリー方言：セッション／ルートスコープのヒント（任意）。クエリでは引き続き明示的な root... パスを使用します。
--sql-dialect	IOTDB_SQL_DIALECT	table	SQL 方言：tree または table
--export-path	IOTDB_EXPORT_PATH	/tmp	クエリ結果のエクスポート先パス

ターゲットレジストリには、ログインに成功した接続のみが含まれます。シークレットではないフィールドを指定して prepare_iotdb_target を呼び出し、その後、ユーザーが明示的に指定した認証情報を connect_iotdb_target に渡して、認証を 1 回試行します。認証情報がない場合はユーザーに確認してください。空またはデフォルトのパスワードを決して試さないでください。明示的に指定された空のパスワードは有効な入力です。

ログインに成功すると、ターゲットがアトミックに公開され、そのターゲット固有の last_known_good_credential が記録されます。接続レイヤーで障害が発生すると、候補は消費されるか、公開済みのターゲットが削除されます。再試行するには、新しい候補を用意し、ユーザーが明示的に指示した後で user_confirmed_retry=true を設定する必要があります。公開されるターゲットの応答では、現在のパスワードと最終確認済みパスワードの両方が伏せられます。

TIMESEEK_IOTDB_TARGETS_FILE が設定されている場合、接続の成功時にデフォルトで接続情報が保存されます。ローカルの Java CLI では、iotdb-target-cli を使用してまったく同じターゲットを再利用できます。

iotdb-target-cli --target-id cloud \
  --cli /opt/iotdb/sbin/start-cli.sh -- -e "SHOW VERSION"

ラッパーは呼び出しのたびに検証済みターゲットを再読み込みし、そのホスト、ポート、方言、ユーザー名、最終確認済みパスワードを渡します。Java CLI はこのオプションをサポートしていないため、start-cli.sh には -db を渡しません。テーブルデータベースを選択するには、SQL の USE <database> を使用してください。-db をサポートする import-data.sh と import-data.bat には、テーブルターゲットのデータベースが自動的に設定されます。検証済みの空のパスワードは -pw を省略することで表され、コマンドのプレビューでは空でないパスワードが伏せられます。start-cli.sh を直接呼び出しても、ターゲットレジストリは読み込まれません。

パフォーマンスの最適化

IoTDB MCP サーバーには、以下のパフォーマンス最適化機能が含まれています。

1. セッションプール管理：最適化されたセッションプール設定を使用し、最大 100 の同時セッションをサポートします
2. フェッチサイズの最適化：クエリのフェッチサイズを 1024 に設定します
3. 接続の再試行：接続失敗時の自動再試行機構が設定されています
4. タイムアウト管理：信頼性を高めるため、セッションの待機タイムアウトを 5000 ミリ秒に設定します
5. エクスポート機能：クエリ結果を CSV または Excel 形式でエクスポートできます

前提条件

• Python 環境
• uv パッケージマネージャー
• IoTDB のインストール
• MCP サーバーの依存関係

開発

# Clone the repository
git clone https://github.com/apache/iotdb-mcp-server.git
cd iotdb-mcp-server

# Create virtual environment
uv venv
source venv/bin/activate  # or `venv\Scripts\activate` on Windows

# Install development dependencies
uv sync

Claude Desktop との連携

Claude Desktop の設定ファイルで MCP サーバーを設定します。

macOS

場所：~/Library/Application Support/Claude/claude_desktop_config.json

Windows

場所：%APPDATA%/Claude/claude_desktop_config.json

コマンドフィールドに uv 実行ファイルのフルパスを指定する必要がある場合があります。MacOS／Linux では which uv、Windows では where uv を実行すると確認できます。

Claude Desktop の設定例

以下の設定を Claude Desktop の設定ファイルに追加します。

{
  "mcpServers": {
    "iotdb": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/your_username/iotdb-mcp-server/src/iotdb_mcp_server",
        "run",
        "server.py"
      ],
      "env": {
        "IOTDB_HOST": "127.0.0.1",
        "IOTDB_PORT": "6667",
        "IOTDB_USER": "root",
        "IOTDB_PASSWORD": "",
        "IOTDB_DATABASE": "test",
        "IOTDB_SQL_DIALECT": "table",
        "IOTDB_EXPORT_PATH": "/path/to/export/folder"
      }
    }
  }
}

注：--directory パラメーターのパスは、実際にクローンしたリポジトリのパスに置き換えてください。

エラー処理とロギング

IoTDB MCP Server には、包括的なエラー処理とロギング機能が備わっています。

1. ログレベル：ログレベルはINFOに設定されており、コンソールでサーバーのステータスを確認できます。
2. 例外処理：すべてのデータベース操作に例外処理が含まれているため、エラー発生時も適切に処理し、わかりやすいエラーメッセージを表示できます。
3. セッション管理：使用したセッションを自動的に閉じ、リソースリークを防ぎます。
4. パラメーター検証：ユーザーが入力したSQLクエリを基本的に検証し、許可された種類のクエリのみが実行されるようにします。

Docker のサポート

プロジェクトルートのDockerfileを使用して、IoTDB MCP Server のコンテナーイメージをビルドできます。

# Build Docker image
docker build -t iotdb-mcp-server .

# Run container
docker run -e IOTDB_HOST=<your-iotdb-host> -e IOTDB_PORT=<your-iotdb-port> -e IOTDB_USER=<your-iotdb-user> -e IOTDB_PASSWORD=<your-iotdb-password> iotdb-mcp-server