LocalAiMCP

LocalAI 向けのステートレスで非同期な FastMCP コントロールプレーン。バンドルされている LocalAI Swagger には 114 パス / 123 オペレーション が含まれており、123 すべてが型付けされ検証済みの呼び出し可能オブジェクトを通じて使用可能です。毎回の MCP リクエストで約 123 個のオペレーションスキーマをモデルに送信しないように、厳選されたセットのみが直接公開されます。それ以外はすべてオンデマンドで検出・実行可能です。

2 つの Swagger WebSocket オペレーションは、制限付きの 1 回限りの交換として実装されています。マルチパートルートはファイルアップロードをサポートし、バイナリレスポンスは ./data/output に保存でき、十分に小さい場合は base64 としてインラインで返されます。

実行

git clone https://github.com/twinlunarstarz-dev/LocalAiMCP.git
cd LocalAiMCP
cp .env.example .env
# Edit LOCALAI_BASE_URL / LOCALAI_API_KEY if needed.
docker compose up -d --build

MCP エンドポイントは次のとおりです:

http://localhost:8000/mcp

VS Code / Zoo Code または別の Streamable HTTP MCP クライアントでは、その URL をリモート MCP サーバーエンドポイントとして使用します。コンテナは LocalAI に対してデフォルトで host.docker.internal:8080 を使用し、Linux の host-gateway マッピングを含みます。

Related MCP server: mcp-file-system-lmstudio

厳選されたツールサーフェス

サーバーはデフォルトでは 123 すべての LocalAI オペレーションを公開しません。デフォルトのプリセットは、20 個の一般的に有用なオペレーションツールと、5 個の固定された検出・システムヘルパーを公開します。

デフォルトで直接公開されるオペレーションツール:

# System/model information
get_system_info
get_metrics
get_token_metrics
list_models
list_model_capabilities
get_backend_monitor

# Generation/media
chat
complete_text
generate_image
inpaint_image
generate_sound
generate_video
text_to_speech
text_to_speech_with_voice

# Voice
list_voice_profiles
create_voice_profile
analyze_voice
verify_speakers

# 3D
generate_3d_asset
remesh_3d_asset

5 個の固定 MCP ヘルパーは次のとおりです:

list_additional_tools
search_additional_tools
execute_additional_tool
server_health
schema_audit

したがって、デフォルトの tools/list サーフェスは約 128 ではなく 25 ツール です。正確な数は設定可能です。

直接表示する LocalAI オペレーションの設定

LOCALAI_MCP_EXPOSED_TOOLS に、セマンティックなオペレーション名のカンマ区切りリストを設定します:

LOCALAI_MCP_EXPOSED_TOOLS=chat,list_models,generate_image,text_to_speech,generate_3d_asset

特別な値:

*       expose all 123 Swagger operations directly
none    expose no Swagger operations directly; use only the gateway/system helpers
gateway-only  same as none

空または未設定の値は、組み込みの 20 オペレーションのプリセットを使用します。無効な名前は、黙って消えるのではなく起動を失敗させます。

直接公開の変更は、MCP クライアントが tools/list で受け取る内容にのみ影響します。LocalAiMCP から隠されたオペレーションが削除されるわけではありません。

追加ツールゲートウェイ

あまり一般的でないツールは内部の型付きレジストリに保持され、3 つの小さなツールを通じてアクセスされます。

list_additional_tools

隠されたツール名の完全なソート済みリストを返し、スキーマの重いものは何も返しません。モデルが毎回のリクエストでそれらのスキーマを恒久的に保持することなく、オンデマンドで隠されたカタログ全体を調べられるように、意図的にコンパクトになっています。

search_additional_tools

平易な言葉での目標または正確なツール名を使用して、隠されたツールのみを検索します。各一致は次を返します:

• セマンティックなツール名

• 詳細な目的・入力・出力の説明

• タグ

• 完全な入力 JSON スキーマ

例:

search_additional_tools(query="detokenize token ids")
search_additional_tools(query="transcribe audio")
search_additional_tools(query="install a backend")
search_additional_tools(query="inspect request traces")

execute_additional_tool

セマンティックな名前で隠された機能を実行します:

{
  "tool_name": "detokenize",
  "arguments": {
    "request": {
      "model": "my-model",
      "tokens": [1, 42, 9001]
    }
  }
}

arguments オブジェクトは、直接公開されたオペレーションで使用される同じ生成済み Pydantic スキーマに対して検証されます。無効または不明なフィールドは、LocalAI リクエストが行われる前に検証エラーと期待される入力スキーマを返します。これは curl スタイルのディスパッチャではありません。モデルは HTTP メソッドやルートではなく、セマンティックなツール名と型付き引数を使用します。

直接公開されたオペレーションは、execute_additional_tool によって意図的に拒否されます。クライアントは通常の MCP ツールを直接呼び出す必要があります。

以前の高度な raw_request エスケープハッチと probe_safe_endpoints ヘルパーは、隠された追加ツールとして保持されます。したがって、tools/list を削減してもこれらの機能は失われません。

LLM 向けの説明

レジストリは、モデルが事前の LocalAI API 知識を必要としないように設計されています:

• ツール名は HTTP ルートやメソッドを反映するのではなく、タスクを説明します。

• すべての型付き HTTP オペレーションは、その目的、期待される入力、および成功時の出力を明記します。

• JSON リクエストスキーマにはフィールドレベルの説明が含まれ、Swagger が Request のようなことだけを言う場合やフィールドを文書化しないままにする場合には、控えめなフォールバックガイダンスも含まれます。

• 参照されるリクエストオブジェクトは、有用なトップレベルフィールドを説明に直接表示します。

• レスポンスの説明は、データが data、text、events、base64、または saved_path のどこに現れるかを説明します。

• 検索は、隠されたツールが関連する場合にのみ完全な入力スキーマを返します。

• カスタムヘッダーや呼び出しごとのタイムアウトなどのラッパー配管は、通常の型付きオペレーションからは除外されます。

たとえば、隠されたツール detokenize は、そのリクエストに以下が含まれることを説明します:

• tokens: テキストに戻すための整数のトークン ID

• model: 使用するトークナイザーを持つ LocalAI モデル名またはエイリアス

また、JSON レスポンスにはデトークン化されたテキストである content が含まれることも説明します。

設計

• FastMCP 3.4.7。再現性のために固定されています。

• Streamable HTTP + ステートレスモード。検出と実行が会話・セッション状態ではなくプロセスローカルの不変レジストリを使用するため、複数の Uvicorn ワーカーは安全です。

• httpx による非同期 LocalAI I/O。独立した呼び出しは並行して実行できます。

• セマンティックな名前と生成された入力検証を備えた 123 個の型付き Swagger オペレーション呼び出し可能オブジェクト。設定されたサブセットのみが FastMCP に直接登録されます。

• 隠されたオペレーションのためのオンデマンドゲートウェイ。毎回のリクエストで全てのスキーマを公開することなく、LocalAI の完全な機能を維持します。

• オーディオ、画像、GLB ファイル、ブランディングアセット、音声プロファイルのためのマルチパートサポート。ファイル引数は data: URI、base64:<data>、HTTP(S) URL、または /data 配下のファイルを受け入れます。

• オーディオ・画像・GLB レスポンスのためのバイナリサポート。小さなペイロードは base64 として返されます。バイナリペイロードは /data/output に保存することもできます。

• SSE 対応レスポンス処理は、LocalAI の SSE イベントを構造化された結果に集約します。

• バックエンドログのストリーミングと、制限付き交換を使用したリアルタイムオーディオ変換のためのWebSocket サポート。

• LOCALAI_API_KEY によるベアラー認証。トークンはコードに保存されず、MCP クライアントに返されることもありません。

レスポンスラッパー

型付き HTTP オペレーションは、予測可能なラッパーを返します:

• ok: LocalAI が成功した HTTP ステータスを返したかどうか

• status_code: LocalAI の HTTP ステータス

• elapsed_ms: リクエストの所要時間

• data: 解析された JSON レスポンスボディ

• text: テキストレスポンス

• events: 収集された SSE data: ペイロード

• base64、size_bytes、mime_type、saved_path: 該当する場合のバイナリレスポンスのメタデータ・コンテンツ

レスポンスボディを消費する前に必ず ok を確認してください。

ファイル入力

マルチパートツールでは、ファイル引数は次のいずれかになります:

• data:<mime>;base64,<payload>

• base64:<payload>

• MCP コンテナが取得できる http:// または https:// URL

• LOCALAI_MCP_FILE_ROOT 配下のローカルパス（Compose では /data）

Compose ファイルは ./data を /data にマウントします。

LocalAI のストリーミング動作

stream=true を設定する LocalAI リクエストボディは変更されずに転送されます。LocalAI が text/event-stream で応答する場合、MCP 呼び出しは SSE data: イベントを収集し、LocalAI ストリームが終了したときにそれらを返します。

2 つの Swagger WebSocket ルートは特別にマッピングされます:

• stream_backend_logs: モデルのバックエンドログメッセージを max_messages まで収集してから閉じます。

• stream_audio_transform: 1 つのセッション・設定オブジェクトと base64 PCM フレームを送信し、変換されたメッセージを max_messages まで収集してから閉じます。

これらは LOCALAI_MCP_EXPOSED_TOOLS に応じて直接公開または非表示になります。非表示の WebSocket ツールは execute_additional_tool を通じて実行可能なままです。

検証

リポジトリのテストは以下を検証します:

• 正確な Swagger カバレッジ: 114 パス / 123 オペレーション

• 123 個の一意でレビュー済みのセマンティック名

• デフォルトの厳選された公開数と MCP の tools/list の数

• 非表示名の完全なカタログ

• 非表示の検索が実際の説明と生成された入力スキーマを返すこと

• 非表示の実行がネットワークアクセスの前に引数を検証すること

• すべての非 WebSocket オペレーションの説明が入力と出力を説明していること

• 参照されるリクエスト・レスポンススキーマが実際のフィールドを表示すること

• detokenize がオンデマンドで有用なトークン・モデル・コンテンツのガイダンスを公開すること

• WebSocket の検出、レスポンスのラッピング、バイナリ処理

• ビルドされたホイールにバンドルされた 4 つの Swagger ペイロード部分すべてが含まれること

依存関係をインストールしてローカルで実行:

python -m pip install -e '.[test]'
pytest

コンテナ検証:

docker compose config
docker compose build

MCP クライアントは http://localhost:8000/mcp に対して通常の MCP initialize ハンドシェイクを実行する必要があります。

設定

セキュリティに関する注意

追加ツールゲートウェイは、モデル・バックエンドのインストール・削除、タスク・ジョブの制御、トレース・ログのクリア、ブランディング、ノード予算、音声プロファイル管理など、LocalAI の管理・破壊的操作を引き続き実行できます。tools/list からツールを非表示にするとコンテキストサイズが削減されますが、これは認可境界ではありません。認証とネットワークアクセス制御を前面に配置せずに、ポート 8000 を信頼できないネットワークに公開しないでください。