InfluxDB MCP Server

InfluxDB v2 MCP サーバー

InfluxDB OSS API v2 を使用して、InfluxDB v2 インスタンスへのアクセスを提供する Model Context Protocol（MCP）サーバーです。主に Claude Code で構築されています。

機能

この MCP サーバーが提供するもの：

• リソース：組織、バケット、測定データへのアクセス
• ツール：データの書き込み、クエリの実行、データベースオブジェクトの管理
• プロンプト：一般的な Flux クエリと Line Protocol 形式のテンプレート

リソース

サーバーは次のリソースを公開します。

1. 組織一覧：influxdb://orgs

   • InfluxDB インスタンス内のすべての組織を表示します

2. バケット一覧：influxdb://buckets

   • メタデータとともにすべてのバケットを表示します

3. バケットの測定データ：influxdb://bucket/{bucketName}/measurements

   • 指定したバケット内のすべての測定データを一覧表示します（INFLUXDB_ORG を使用）

4. データのクエリ：influxdb://query/{orgName}/{fluxQuery}

   • Flux クエリを実行し、結果を JSON として返します（headers と、すべての結果テーブルにわたる各行のレコード）

テンプレート変数（bucketName、orgName、fluxQuery）は、encodeURIComponent などを使ってパーセントエンコードする必要があります。これにより、スペースや / を含む名前や複数行のクエリを URI 内で正しく扱えます。

ツール

サーバーは次のツールを提供します。

1. write-data：Line Protocol 形式で時系列データを書き込みます

   • パラメーター：org、bucket、data、precision（任意）
   • INFLUXDB_ORG / INFLUXDB_BUCKET が設定されている場合、org と bucket は省略可能で、省略するとそれらの値が使われます

2. query-data：Flux クエリを実行します

   • パラメーター：org、query
   • INFLUXDB_ORG が設定されている場合、org は省略可能で、省略するとその値が使われます

3. create-bucket：新しいバケットを作成します

   • パラメーター：name、orgID、retentionPeriodSeconds（任意、整数の秒数。無期限の保持にするには省略するか、0 を指定します）

4. create-org：新しい組織を作成します

   • パラメーター：name、description（任意）

プロンプト

サーバーは次のプロンプトテンプレートを提供します。

1. flux-query-examples：一般的な Flux クエリの例
2. line-protocol-guide：InfluxDB Line Protocol 形式のガイド

設定

サーバーには、以下の環境変数が必要です。

• INFLUXDB_TOKEN（必須）：InfluxDB API の認証トークン
• INFLUXDB_URL（任意）：InfluxDB インスタンスの URL（デフォルトは http://localhost:8086）
• INFLUXDB_ORG（任意）：一部の操作で使用するデフォルトの組織名。設定すると、write-data ツールと query-data ツールで org を省略できます
• INFLUXDB_BUCKET（任意）：デフォルトのバケット名。設定すると、write-data ツールで bucket を省略できます
• DEBUG（任意）：mcp:* を設定すると、すべての MCP メッセージを stderr に記録します。クエリテキストと書き込まれたデータも含まれるため、本番環境では無効にしてください

以下の変数は、Streamable HTTP トランスポートにのみ適用されます（HTTP トランスポートのセキュリティを参照）。

• MCP_HTTP_HOST（任意）：待ち受けるインターフェース（デフォルトは 127.0.0.1。--host と同じです）
• MCP_AUTH_TOKEN（任意）：設定すると、すべてのリクエストで Authorization: Bearer <token> の送信が必要です。ループバック以外のインターフェースで待ち受ける場合は必須です
• MCP_ALLOWED_HOSTS（任意）：Host ヘッダーで許可するホスト名をカンマ区切りで指定します（ポートは無視されます）。デフォルトは localhost,127.0.0.1,[::1] と、ループバック上のバインドアドレスです。未設定の場合、他のインターフェースでは Host のチェックを行いません
• MCP_HTTP_ALLOW_UNAUTHENTICATED（任意）：true を設定すると、MCP_AUTH_TOKEN がなくてもループバック以外のインターフェースで待ち受けます。たとえば、認証を代行するリバースプロキシの背後で使用する場合に設定します
• MCP_HTTP_BODY_LIMIT（任意）：リクエスト本文の最大サイズ（デフォルトは 4mb。b、kb、mb のサフィックスを指定できます）。非常に大きな write-data バッチを送信する場合は、値を大きくしてください

InfluxDB へのリクエストは、レスポンスの読み取り時間を含めて、10 秒後にタイムアウトします（クエリは 60 秒、書き込みは 30 秒）。

インストール

Smithery を使用してインストール

Smithery を使用して、Claude Desktop 用の InfluxDB MCP Server を自動的にインストールします。

npx -y @smithery/cli install @idoru/influxdb-mcp-server --client claude

オプション 1：npx で実行（推奨）

# Run directly with npx
INFLUXDB_TOKEN=your_token npx influxdb-mcp-server

オプション 2：グローバルにインストール

# Install globally
npm install -g influxdb-mcp-server

# Run the server
INFLUXDB_TOKEN=your_token influxdb-mcp-server

オプション 3：ソースからインストール

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

# Install dependencies
npm install

# Run the server
INFLUXDB_TOKEN=your_token npm start

Node.js 20 以降が必要です。

influxdb-mcp-server は、デフォルトで stdio トランスポートを使用します。--stdio で明示的に指定することも、ポート番号を省略可能な --http オプションを指定して、Streamable HTTP トランスポートでサーバーを起動することもできます（デフォルトのポートは 3000 です）。このモードでは、--host を指定しない限り、127.0.0.1 で待ち受ける内部 Express.js サーバーを使用します。

# Start with Streamable HTTP transport on default port 3000
INFLUXDB_TOKEN=your_token npm start -- --http

# Start with Streamable HTTP transport on a specific port
INFLUXDB_TOKEN=your_token npm start -- --http 8080

グローバルにインストールした場合、または npx を使用する場合は、次のコマンドを実行できます。

INFLUXDB_TOKEN=your_token influxdb-mcp-server --http
# or explicitly force stdio
INFLUXDB_TOKEN=your_token influxdb-mcp-server --stdio
# or
INFLUXDB_TOKEN=your_token influxdb-mcp-server --http 8080

HTTP トランスポートのセキュリティ

HTTP エンドポイントにアクセスできる人は誰でも、サーバーの INFLUXDB_TOKEN を使って InfluxDB の読み書きができるため、HTTP トランスポートはデフォルトで制限されています。

• 127.0.0.1 のみで待ち受けます。
• ループバックでは、Host ヘッダーが localhost、127.0.0.1、[::1] のいずれでもないリクエストを拒否します。これにより、ブラウザーで開いているウェブサイトからの DNS リバインディング攻撃を防ぎます。
• MCP_AUTH_TOKEN が設定されていない限り（または MCP_HTTP_ALLOW_UNAUTHENTICATED=true が設定されていない限り）、他のインターフェースでの待ち受けを拒否します。

サーバーをネットワーク上またはコンテナーからアクセスできるようにするには、ベアラートークンを必須にしてください。

INFLUXDB_TOKEN=your_token MCP_AUTH_TOKEN="$(openssl rand -hex 32)" \
  influxdb-mcp-server --http 3000 --host 0.0.0.0

クライアントは、各リクエストで Authorization: Bearer <MCP_AUTH_TOKEN> を送信します。DNS リバインディングへの対策をさらに強化するには、クライアントがサーバーへのアクセスに使用するホスト名を MCP_ALLOWED_HOSTS に設定してください。サーバーにお使いのマシン以外からアクセスできる場合は、サーバーの前段で TLS を終端することを推奨します。

Docker

イメージは非特権の node ユーザーで実行され、デフォルトで stdio を使用します。

docker build -t influxdb-mcp-server .
docker run --rm -i -e INFLUXDB_TOKEN=your_token -e INFLUXDB_URL=http://host.docker.internal:8086 influxdb-mcp-server

# Streamable HTTP inside a container must bind 0.0.0.0, so it needs a token
docker run --rm -p 127.0.0.1:3000:3000 -e INFLUXDB_TOKEN=your_token -e MCP_AUTH_TOKEN=your_mcp_token \
  influxdb-mcp-server --http 3000 --host 0.0.0.0

Claude for Desktop との連携

claude_desktop_config.json にサーバーを追加します。

npx を使用する場合（推奨）

{
  "mcpServers": {
    "influxdb": {
      "command": "npx",
      "args": ["influxdb-mcp-server"],
      "env": {
        "INFLUXDB_TOKEN": "your_token",
        "INFLUXDB_URL": "http://localhost:8086",
        "INFLUXDB_ORG": "your_org",
        "INFLUXDB_BUCKET": "your_bucket"
      }
    }
  }
}

ローカルにインストールした場合

{
  "mcpServers": {
    "influxdb": {
      "command": "node",
      "args": ["/path/to/influxdb-mcp-server/src/index.js"],
      "env": {
        "INFLUXDB_TOKEN": "your_token",
        "INFLUXDB_URL": "http://localhost:8086",
        "INFLUXDB_ORG": "your_org",
        "INFLUXDB_BUCKET": "your_bucket"
      }
    }
  }
}

コード構成

サーバーコードは、モジュール化された構成になっています。

• src/
  • index.js - CLI エントリーポイント（引数の解析とトランスポートの選択）
  • server.js - リソース、ツール、プロンプトを登録する MCP サーバーファクトリー
  • config/ - 設定関連のファイル
    • env.js - 環境変数の処理
    • http.js - HTTP トランスポートのオプションと安全性チェック
  • http/ - ストリーミング可能な HTTP トランスポート
    • app.js - Express アプリ（Host の検証、ベアラー認証、ボディサイズ制限）
  • utils/ - ユーティリティ関数
    • influxClient.js - リクエストタイムアウト機能を備えた InfluxDB API クライアント
    • csv.js - Flux CSV レスポンスパーサー
    • flux.js - Flux 文字列のエスケープと URI パラメーターのデコード
    • loggerConfig.js - コンソールロガーの設定と DEBUG トレース
    • traceTransport.js - DEBUG=mcp:* 向けの MCP メッセージトレース
  • handlers/ - リソースおよびツールのハンドラー
    • organizationsHandler.js - Organization の一覧表示
    • bucketsHandler.js - Bucket の一覧表示
    • measurementsHandler.js - Measurement の一覧表示
    • queryHandler.js - クエリの実行
    • writeDataTool.js - データ書き込みツール
    • queryDataTool.js - クエリツール
    • createBucketTool.js - Bucket 作成ツール
    • createOrgTool.js - Organization 作成ツール
  • prompts/ - プロンプトのテンプレート
    • fluxQueryExamplesPrompt.js - Flux クエリの例
    • lineProtocolGuidePrompt.js - Line Protocol ガイド

この構成により、保守性が向上し、テストが容易になり、関心事をより明確に分離できます。

テスト

このリポジトリには、以下を実施する包括的なテストが含まれています。

• InfluxDB を含む Docker コンテナーを起動します
• サンプルデータを登録します
• すべての MCP サーバー機能をテストします
• Docker を使わずに、HTTP トランスポートの Host 検証、認証、制限、および CSV と Flux のヘルパーをテストします

テストを実行するには：

npm test

ライセンス

MIT