infino-ai

Infino MCP サーバー

Infino 向けの MCP サーバーです。AI エージェントが、オブジェクトストレージ上のデータを対象に、キーワード検索、セマンティック検索、ハイブリッド検索、SQL による検索を実行できます。RAG、永続的なエージェントメモリ、自分のファイルの検索を支える検索レイヤーとして、MCP に対応するあらゆるクライアント（Claude Code、Claude Desktop、Cursor、VS Code など）から利用できます。npm では @infino-ai/mcp-server として公開され、公式 MCP Registry では io.github.infino-ai/mcp-server として登録されています（Smithery、Glama、PulseMCP などのカタログにも反映されます）。

• ローカルで埋め込みを生成し、キーは不要です。 セマンティック検索ではローカルモデルを使ってクエリを埋め込むため、埋め込み生成のためにデータがマシンの外へ送られることはありません。
• データを扱うのはエージェントです。 書き込みを含むすべてのツールを常に利用できます。Infino Cloud では、API キーの権限によって接続で実行できる操作が決まります。また、破壊的な呼び出しの前にクライアントが確認できるよう、すべてのツールに MCP アノテーションが付いています。
• ローカルでもホスト型でも利用できます。 ローカルパス、自分のバケット（S3、Azure、または S3 互換ストア）、あるいは API キーを使うホスト型の Infino Cloud エンドポイントを指定できます。
• インデックスは有効な Parquet ファイルです。 テーブルにはデータと検索インデックスがプレーンな Parquet 形式でストレージに保存されます。同じファイルを DuckDB や pyarrow で開けます。エクスポートは不要で、ロックインもありません。

---

目次

• 要件
• クイックスタート
• Claude Code プラグイン（ワンステップでインストール）
• クライアントのセットアップ
  • Claude Code
  • Claude Desktop
  • Cursor
  • VS Code
  • その他の MCP クライアント
• 設定
  • 環境変数
  • ストレージバックエンド
• ツール
• セキュリティとデータの取り扱い
• 検索の仕組み
• トラブルシューティング
• ローカル開発
• ライセンス

---

要件

• Node.js ≥ 20（サーバーは stdio を介して Node プロセスとして実行されます）。
• MCP に対応するクライアント（Claude Code、Claude Desktop、Cursor、VS Code など）。
• Infino からアクセスできるデータ — ローカルディレクトリ、環境内で認証情報を利用できるバケット、または API キーを使うホスト型の Infino Cloud エンドポイント（ストレージバックエンドを参照）。
• 初回実行時に、サーバーはローカル埋め込みモデル（約 90 MB）を一度ダウンロードしてキャッシュします。2 回目以降の埋め込み生成はオフラインで行われます。

---

クイックスタート

通常の使用では、サーバーを直接実行するのではなく、MCP クライアントが stdio を介して起動します。各クライアントの設定形式は共通です。コマンドには npx -y @infino-ai/mcp-server を指定し、環境変数で設定を渡します。提供するデータを指定するには INFINO_MCP_URI を設定します。値にはローカルパスまたはバケット URI を指定できます。省略した場合、サーバーはユーザーごとに永続化されるディレクトリ（~/.infino/mcp）を使うため、再起動後もデータが保持されます。既存のデータを提供するには、INFINO_MCP_URI に独自のパスまたはバケットを指定してください。

{
  "command": "npx",
  "args": ["-y", "@infino-ai/mcp-server"],
  "env": {
    "INFINO_MCP_URI": "/Users/me/.infino/memory"
  }
}

ホスト型 Infino Cloud データベースを提供するには、INFINO_MCP_URI に https://<host>/<database> エンドポイントを指定し、API キーを設定します。ほかの設定は すべて同じです。

{
  "command": "npx",
  "args": ["-y", "@infino-ai/mcp-server"],
  "env": {
    "INFINO_MCP_URI": "https://api.platform.infino.ws/my-database",
    "INFINO_API_KEY": "inf_…"
  }
}

以下の各セクションでは、この設定ブロックを各クライアントのどこに記述するかを示します。

---

Claude Code プラグイン（ワンステップでインストール）

Claude Codeでは、このリポジトリはプラグインマーケットプレイスとしても機能します。プラグインをインストールすると、MCP サーバーに加えて、使い方を説明するスキルと/infino-searchコマンドが一度に設定され、JSON を編集する必要はありません。Claude Code 内で次を実行します。

/plugin marketplace add infino-ai/infino-mcp
/plugin install infino@infino-ai

有効にすると、Infino データ URI（INFINO_MCP_URI）と、Infino Cloud の場合はAPI キーを入力するよう求められます。これで完了です。infino_*ツール、using-infinoスキル、/infino-search <query>が利用可能になります。（その他のクライアントについては、以下のクライアントの設定をご覧ください。）

---

クライアントの設定

Claude Code

CLI でサーバーを追加します。すべてのプロジェクトで利用できるようにするには--scope userを、リポジトリにコミットするには--scope projectを指定します（共有の.mcp.jsonが書き込まれます）。デフォルトのスコープはlocal（このプロジェクトのみ）です。

claude mcp add infino \
  --scope user \
  -e INFINO_MCP_URI=/Users/me/.infino/memory \
  -- npx -y @infino-ai/mcp-server

-eフラグを繰り返し指定して設定を追加できます。例：-e INFINO_MCP_VALIDATE=true。次のコマンドで確認します。

claude mcp list
claude mcp get infino

Claude Desktop

設定ファイルを編集し（存在しない場合は作成して）、Claude Desktop を完全に再起動します。

OS	パス
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "infino": {
      "command": "npx",
      "args": ["-y", "@infino-ai/mcp-server"],
      "env": {
        "INFINO_MCP_URI": "/Users/me/.infino/memory"
      }
    }
  }
}

Cursor

サーバーを**~/.cursor/mcp.json（すべてのプロジェクトで利用可能）または<project>/.cursor/mcp.json**（このプロジェクトのみ）に追加してから、再読み込みします。形式は Claude Desktop と同じです。

{
  "mcpServers": {
    "infino": {
      "command": "npx",
      "args": ["-y", "@infino-ai/mcp-server"],
      "env": {
        "INFINO_MCP_URI": "/Users/me/.infino/memory"
      }
    }
  }
}

VS Code

VS Code（1.102以降）は、ワークスペース内の**.vscode/mcp.json**（またはコマンドパレットから MCP: Open User Configuration を実行して開くユーザーのmcp.json）から MCP サーバーを読み込みます。最上位のキーはserversで、各エントリに"type": "stdio"を指定する点に注意してください。

{
  "servers": {
    "infino": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@infino-ai/mcp-server"],
      "env": {
        "INFINO_MCP_URI": "/Users/me/.infino/memory"
      }
    }
  }
}

その他の MCP クライアント

stdio 経由で MCP を使用するクライアントなら、どれでも利用できます。次のコマンドを起動するよう設定してください。

command: npx
args:    -y @infino-ai/mcp-server
env:     INFINO_MCP_URI=<path-or-bucket-uri>   (plus any options below)

ログはstderrに書き込まれるため、stdout の JSON-RPC ストリームを破損することはありません。デバッグ時は、クライアントのログ取得先を stderr に設定してください。

---

設定

すべての設定は環境変数で行います。設定ファイルや管理が必要なコマンドラインフラグはありません。

環境変数

変数	必須	デフォルト	説明
INFINO_MCP_URI	いいえ	~/.infino/mcp（永続）	提供するデータ：ローカルパス（/Users/me/.infino/memory）、バケット URI（s3://…、az://…）、またはホスト型エンドポイント（https://<host>/<database>、Infino Cloud）。設定されていない場合、再起動後もデータが保持されるよう、ユーザーごとの永続ディレクトリ（~/.infino/mcp）が使用されます。このディレクトリを作成できない場合に限り、プロセス内の一時カタログ（memory://）にフォールバックします。
INFINO_API_KEY	ホスト型 URI の場合	—	ホスト型の https:// エンドポイント用の API キー（inf_…）です。INFINO_MCP_URI が https:// URI の場合に必須です。ローカル接続およびオブジェクトストレージ接続では無視されます。
INFINO_MCP_EMBED_PROVIDER	いいえ	local	埋め込みプロバイダー：local（Hugging Face transformers.js、キー不要、データはマシンの外部に送信されません）または openai（OpenAI、Azure OpenAI の /openai/v1 インターフェイス、互換サーバーなど、OpenAI 互換の /embeddings エンドポイント）。INFINO_MCP_EMBED_BASE_URL が設定されている場合は、openai と推定されます。
INFINO_MCP_EMBED_BASE_URL	openai の場合	—	OpenAI 互換の埋め込み API のベース URL です。例：https://api.openai.com/v1 または https://<resource>.openai.azure.com/openai/v1。サーバーは <base>/embeddings に POST します。
INFINO_MCP_EMBED_API_KEY	いいえ	—	openai プロバイダー用の API キーです。Authorization: Bearer と api-key の両方として送信されるため、OpenAI と Azure OpenAI のどちらにも同じ値を使用できます。認証不要のエンドポイントや、環境に応じた ID を使用するエンドポイントを呼び出す場合は省略してください。
INFINO_MCP_EMBED_MODEL	いいえ	Xenova/all-MiniLM-L6-v2（local） · text-embedding-3-small（openai）	埋め込みモデルです。local の場合は Hugging Face の特徴抽出モデル、openai の場合はモデル名／デプロイ名です。テーブルに保存されたベクトルを生成したモデルと一致させる必要があります。そのため、ベクトルインデックスの次元数も一致させる必要があります（例：text-embedding-3-small は 1536 次元、デフォルトのローカルモデルは 384 次元です）。
INFINO_MCP_VALIDATE	いいえ	オフ	設定されている場合（1／true／yes）、起動時にオブジェクトストアを確認します。これにより、認証情報の誤りやバケットへの接続不能が、最初の検索時ではなく起動時に検出されます。

クラウドの認証情報は、各プロバイダーの標準環境変数から読み込まれます。サーバーはそれらをストアの設定に割り当て、独自の認証情報用変数は追加しません。クラウドの環境 ID（IAM インスタンスロールや Azure マネージド ID）を使用する場合は、認証情報をすべて省略してください。

OpenAI／Azure OpenAI で埋め込みを作成したカタログの提供。 テーブルのベクトル化にデフォルトのローカルモデルではなくホスト型の埋め込みモデルを使用した場合は、クエリとドキュメントのベクトルが一致するよう、サーバーにも同じモデルを指定してください。

"env": {
  "INFINO_MCP_URI": "s3://my-bucket/infino",
  "INFINO_MCP_EMBED_PROVIDER": "openai",
  "INFINO_MCP_EMBED_BASE_URL": "https://my-resource.openai.azure.com/openai/v1",
  "INFINO_MCP_EMBED_API_KEY": "…",
  "INFINO_MCP_EMBED_MODEL": "text-embedding-3-small"
}

モデルは、保存されたベクトルを生成したモデルと一致する必要があります。一致しない場合、類似度が無意味になるか、次元エラーが発生します。キーワード検索と SQL 検索は埋め込みモデルの影響を受けません。

バックエンド	認証情報
AWS S3	AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY（使用する場合は AWS_SESSION_TOKEN、AWS_REGION も）
S3 互換（R2／MinIO／B2）	AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY および AWS_ENDPOINT_URL
Azure Blob	AZURE_STORAGE_ACCOUNT、AZURE_STORAGE_KEY
Infino Cloud（ホスト型）	INFINO_API_KEY — オブジェクトストレージの認証情報は不要です（ストレージはプラットフォームが管理します）

ストレージバックエンド

// Local directory
"env": { "INFINO_MCP_URI": "/Users/me/.infino/memory" }

// AWS S3 — ambient AWS_* credentials, default endpoint
"env": {
  "INFINO_MCP_URI": "s3://my-bucket/infino",
  "AWS_ACCESS_KEY_ID": "…",
  "AWS_SECRET_ACCESS_KEY": "…"
}

// S3-compatible (Cloudflare R2 / MinIO / Backblaze B2) — custom endpoint
"env": {
  "INFINO_MCP_URI": "s3://my-bucket/infino",
  "AWS_ENDPOINT_URL": "https://<account>.r2.cloudflarestorage.com",
  "AWS_ACCESS_KEY_ID": "…",
  "AWS_SECRET_ACCESS_KEY": "…"
}

// Azure Blob
"env": {
  "INFINO_MCP_URI": "az://my-container/infino",
  "AZURE_STORAGE_ACCOUNT": "…",
  "AZURE_STORAGE_KEY": "…"
}

// Infino Cloud (hosted) — the database is the last path segment
"env": {
  "INFINO_MCP_URI": "https://api.platform.infino.ws/my-database",
  "INFINO_API_KEY": "inf_…"
}

ホスト型接続でも、検索、SQL、書き込みの各ツールはローカルの場合とまったく同じように動作します。異なるのはデータの保存場所だけです。圧縮とガベージコレクションはサーバー側で処理されるため、クライアントの操作としては公開されません。セマンティック検索とハイブリッド検索では、引き続きこのサーバー上でクエリをローカルに埋め込み処理するため、INFINO_MCP_EMBED_MODEL はホスト型テーブルに保存されたベクトルを生成したモデルと一致させる必要があります（上記の OpenAI／Azure OpenAI に関する注意を参照）。データを別のユーザーが取り込んだ場合は、特に重要です。

---

ツール

ツール	引数	機能
infino_semantic_search	table, query, k, column?, vectorColumn?, columns?, filter?	意味に基づいて文章を検索します。ローカルモデルでクエリを埋め込み（キー不要）、ベクトル類似度で順位付けします。言い換えや同義語にも対応します。score は距離を示します（小さいほど近いことを表します）。任意の filter（{column, query, mode?}）を指定すると、キーワード列が先に一致した行にランキングを絞り込めます（プッシュダウン事前フィルター）。任意の columns で各検索結果が返すフィールドを指定できます（例：引用用のパスと行範囲）。デフォルトではテキスト列が返され、_id と score は常に含まれます。
infino_keyword_search	table, query, k, column?, mode?, columns?	BM25 全文検索です。正確な用語、識別子、エラーコード、製品名の検索に適しています。score は関連度を示します（大きいほど良好です）。mode は or（デフォルト）または and です。
infino_hybrid_search	table, query, k, column?, vectorColumn?, mode?, columns?	キーワード検索とセマンティック検索を 1 回のランキング処理で融合します。テキスト列に対する BM25 とベクトル類似度を組み合わせるため、文字どおりの用語と意味の両方に一致する行が上位に表示されます。score は融合後の順位を示します（大きいほど良好です）。
infino_token_match	table, query, column?, mode?, limit?	順位付けなしのキーワードフィルターです。テキスト列にトークンが含まれる行を返します。関連度順ではなく、一致した結果そのものが必要な場合に使用します。
infino_exact_match	table, value, column?, limit?	インデックス付き列（タグ、ステータス、ID 文字列）に対する、順位付けなしの完全一致フィルターです。
infino_count	table, query, column?, mode?	行を取得せずに、キーワードクエリに一致する行数を数えます。テキスト列を対象にすばやく集計します。一致した行を取得するには、infino_keyword_search または infino_token_match を使用します。
infino_sql	query, embed?	件数の取得、フィルター、結合、集計に使用する SQL です。エンジンの検索テーブル関数を内部で呼び出せます。{{name}} プレースホルダーには embed[name] のベクトルが代入されます。DDL／DML を含む任意の単一ステートメントを実行できます。
infino_list_tables	—	接続中のカタログにあるテーブルを一覧表示します。
infino_describe_table	table	テーブルの列名と型を表示します。
infino_create_database	—	接続先として指定されたデータベースをプロビジョニングします（Infino Cloud）。ローカルでは何もせず成功します。冪等です。
infino_create_table	table, columns, fts?, vector?	{column: type} 記述子からテーブルを作成します。fts に対して全文検索インデックスを作成します（デフォルトではすべての large_utf8 列が対象）。vector: true を指定すると、サーバーの埋め込みモデルに合わせたサイズの embedding 列とコサインインデックスが追加されます。
infino_drop_table	table, purge?	テーブルを削除します。デフォルトではストレージオブジェクトも削除されます。purge: false を指定すると、名前の登録だけを解除します。
infino_add_documents	table, documents	行を追加します（1 回の呼び出しで 1 回コミット）。ベクトルがない行はテキスト列からまとめて埋め込みます。結果には appended と embedded が報告されます。列ではないキーを指定するとエラーになります。
infino_update_documents	table, predicate, documents	SQL 述語に一致する行を、新しいドキュメントで 1 対 1 に置き換えます（ベクトルがない場合は埋め込みます）。永続ストレージのみで使用できます。
infino_delete_documents	table, predicate	SQL 述語に一致する行を削除します。永続ストレージのみで使用できます。
検索結果には列の値がすべて返されます。columns 引数はエンジン（組み込みまたはホスト型）にそのまま渡される射影なので、テーブル内のどの列も各検索結果に含められます。大きな k で結果をコンパクトにするには ["id"]、引用用の ID と全文を含めるには ["id", "text"]、フィルタリングにはメタデータ列を指定します。デフォルトではテキスト列が対象となり、_id と score は常に含まれます。また、切り詰められることはありません。結果を小さく保つには、射影する列を減らすか、より小さな k を指定してください。すべての検索レスポンスには score_kind も含まれ、score が距離（セマンティック検索：小さいほど近い）なのか、関連度（キーワード検索とハイブリッド検索：大きいほど高い）なのかを示します。

通常の検索では、埋め込みと射影を自動で行う専用の検索ツールを使用してください。infino_sql はフィルター、結合、集計用であり、検索テーブル関数の結果に対しても使用できるため、1 つのクエリでランキングと集計を同時に実行できます。

データの書き込み

エージェントがたどる書き込み手順です。各ステップは 1 回のツール呼び出しと 1 回のコミットで構成されます。

1. ホスト型データベースから 404 が返された場合は、infino_create_database を実行します。
2. キー列には utf8、テキスト列には large_utf8 を指定し、セマンティック検索には vector: true を設定して infino_create_table を実行します。サーバーが埋め込みモデルに合わせてベクトル列のサイズを設定するため、エージェントが次元数を入力することはありません。結果は保持してください。どの列にインデックスが設定されているかを記録しているのは、その indexes フィールドだけです。
3. 1 回の呼び出しにつき数十行を infino_add_documents に渡し、必ずキーを含めてください。ベクトルがない場合は、1 回のバッチで埋め込みが生成されます。
4. 行を置き換えるには、キー述語で infino_delete_documents を実行してから、再度追加します。行を削除するには、まず infino_count で述語を確認してください。

1 回のツール呼び出しで数十件のドキュメントを渡せます。コーパス全体を扱う場合は、infino CLI（infino ingest は同じ URI に対して Parquet または NDJSON を受け付けます）か SDK を使用してください。CLI ではエンジンと同様にベクトルを自分で用意する必要があるため、行に embedding 列を含めるか、テキストを読み込んでキーワード検索を使用してください。

サーバー側に書き込み制限はありません。また、廃止された INFINO_MCP_ENABLE_WRITES 変数は無視されます（設定されている場合、サーバーは stderr にその旨を出力します）。Infino Cloud では、API キーの権限によって接続で実行できる操作が制限されます。読み取り専用キーではすべての書き込みが拒否され、ツールの結果には書き込み権限のあるキーを発行するよう表示されます。ローカル環境では、エージェントが変更してよいデータのみをサーバーの接続先に指定してください。

---

セキュリティとデータの取り扱い

このサーバーはクライアントの隣でローカルに実行され、データと認証情報をユーザーのマシン上に保持します。

• ローカルで実行し、受信リスナーはありません。 MCP クライアントのサブプロセスとして stdio 経由で実行され、ネットワークリスナーを開きません。デフォルトのローカル／バケットモードでは、リモートサービスに接続しません。INFINO_MCP_URI がホストされた https:// エンドポイントの場合、検索、SQL、（有効にしている場合は）書き込みを行うため、そのエンドポイントに対して 送信 TLS 呼び出しを行います。そのため、リクエスト内のデータは設定したホストサービスに送信され、それ以外には送信されません。
• デフォルトでは、埋め込みのためにデータを送信しません。 デフォルトのプロバイダーでは、クエリとドキュメントの埋め込みにローカルモデルを使用するため、テキストがサードパーティの埋め込み API に送信されることはなく、用意したり漏えいしたりする埋め込み API キーもありません。ホストモードでは、テキストではなく生成されたベクトルのみが Infino Cloud エンドポイントに送信されます。OpenAI 互換プロバイダーを設定した場合、埋め込み対象のテキストは指定したエンドポイントに送信されます。
• 認証情報は環境内に保持されます。 ストレージ認証情報（AWS_*／AZURE_*）とホスト API キー（INFINO_API_KEY）は環境変数から読み込まれ、設定したストアまたはエンドポイントへの接続にのみ使用されます。ログに記録されたり、ツールの出力として返されたりすることはありません。
• 書き込み権限を持つユーザーはサーバーの外部で決まります。 書き込みを含むすべてのツールセットを、エージェントは常に利用できます。Infino Cloud では API キーの権限によって接続で実行できる操作が制限されます（読み取り専用キーでは、すべての書き込みが拒否されます）。ローカルでは、エージェントが変更してもよいデータのみをサーバーの接続先に指定してください。各ツールには MCP アノテーション（readOnlyHint、destructiveHint）が付いているため、クライアントは独自の基準で確認を求めることができます。
• 最小権限の原則。 INFINO_MCP_URI にはタスクに必要な最小範囲のデータセットを指定し、そのバケット／プレフィックスに限定されたストレージ認証情報を用意してください。

---

検索の仕組み

セマンティック検索では Hugging Face transformers.js を使ってローカルで埋め込みを行います（デフォルトでは all-MiniLM-L6-v2、384 次元。INFINO_MCP_EMBED_MODEL で変更できます）。サーバーは、取り込むドキュメント（infino_add_documents 経由）とクエリの 両方 を同じモデルで埋め込むため、同じベクトル空間で対応します。

INFINO_MCP_EMBED_MODEL を変更する場合、テーブルのベクトルインデックスは新しいモデルの次元と一致している必要があります。異なるモデルで生成された埋め込みは比較できず、次元が一致しないと検索時にエラーになります。

---

トラブルシューティング

症状	考えられる原因／対処法
クライアントに Infino ツールが表示されない	サーバーが起動していません。クライアントの MCP ログ（stderr）を確認してください。npx が PATH にあり、INFINO_MCP_URI が設定されていることを確認してください。設定を編集した後は、クライアントを完全に再起動してください。
INFINO_MCP_URI is required	環境変数がサブプロセスに渡されていません。GUI クライアントでは、サーバーの env ブロック内に環境変数を設定する必要があります（プロセスはシェルの環境を継承しません）。
書き込み時にキーが「拒否された、または書き込み権限がない」と表示される	Infino Cloud で API キーが読み取り専用（HTTP 403）か、誤ったキーです。書き込み権限のあるキーを発行し、それを使ってサーバーを再起動してください。
書き込み時に「別の書き込み処理がコミット競合に勝ちました」と表示される	2 つの書き込み処理が同時に同じテーブルに書き込み、この呼び出しは反映されませんでした。再度実行してください。
最初のクエリが遅い	埋め込みモデルのダウンロードが初回のみ発生します（約 90 MB）。以降の実行ではキャッシュが使われます。
ホストされた https:// URI で認証エラーが発生する	INFINO_API_KEY が未設定か、誤っているか、そのデータベースへのアクセス権がありません。キー（inf_…）と、URI の最後のパス要素がアクセス可能なデータベースであることを確認してください。
セマンティック検索で次元／ベクトルエラーが発生する	テーブルのベクトルインデックスが埋め込みモデルの次元と一致していません。再取り込みするか、インデックスの構築に使用したモデルを INFINO_MCP_EMBED_MODEL に設定してください。

ローカル開発

このサーバーは公開されている @infino-ai/infino Node バインディングに依存しており、ほかの依存関係と同様に、パブリック npm から解決されます。

npm install
npm run build
INFINO_MCP_URI=/path/to/data node dist/index.js   # runs on stdio

ローカルビルドを実際に試すには、stdio 経由で node /absolute/path/dist/index.js をクライアントに指定するか、MCP Inspector を使用します。

npx @modelcontextprotocol/inspector node dist/index.js

---

ライセンス

Apache-2.0