Local AI MCP

Local AI MCP

お使いのマシン上にあるあらゆるローカルモデルランタイムを扱う、1つの MCP サーバーです。GPU に適したモデルを判断し、指示がない限りプロンプトをクラウドに送信しません。

Local AI MCP は、エージェント（Claude、Cursor、VS Code など）に Ollama、LM Studio、llama.cpp、Docker Model Runner、MLX、vLLM、Foundry Local を一元管理するコントロールプレーンを提供します。エージェントは、インストール済みおよびロード済みのモデルを確認し、VRAM に実際に収まるかを調べ、モデルを使える状態にし、単一の delegate 呼び出しで最適なローカルモデルに処理を委任できます。

# illustrative session
You:    Summarise these 40 pages of meeting notes locally, I don't want them in the cloud.
Agent:  → delegate { task: "summarize", prompt: "...", contextLength: 32768 }
        ← routing: ollama / qwen3:14b — already loaded (no load cost); general model; fits: gpu
          local: true · 412 tokens · 38 tok/s

選ぶ理由

• ハードウェアを把握します。 fit_check はモデルの実際のレイヤー構造を基に KV キャッシュのサイズを算出し、GPU ごとの VRAM を合算して、GPU と CPU への部分オフロードをモデル化し、Apple Silicon のユニファイドメモリにも対応します。「このモデルは実行できるか、どこで実行するか？」に、推測ではなく数値で答えます。
• 複数のランタイムに対応します。 Ollama と LM Studio の両方を使用している場合、各呼び出しはモデルが実際にあるランタイムに送られます。pull、load、unload などのライフサイクル操作は、対象のランタイム1つだけに作用します。
• デフォルトでデータをローカルに保ちます。 Moonshot などのホステッドプロバイダーはオプトイン方式です。provider 引数を指定しない呼び出しでは、プロバイダーは使用されません。すべての結果に provider、host、local が含まれるため、推論がどこで実行されたかを確認できます。
• チャットだけでなく運用にも対応します。 進捗を表示しながらの pull、コンテキストサイズを指定した load、空き容量を確保するための最終使用時刻が最も古いモデルの退避、Time to First Token とトークン毎秒のベンチマーク、マシンに適した GGUF 量子化モデルの Hugging Face 検索ができます。

エージェントへの質問例

• 「このノート PC でコーディングに使えるモデルは？」→ suggest_model、続けて ensure_model
• 「GPU の空き容量を増やして。」→ list_loaded、続けて unload_model（または free-vram プロンプトを使用）
• 「インストール済みのコーダーモデルをベンチマークして、最速のものを教えて。」→ benchmark { models: [...] }
• 「12 GB のカードに収まる、新しい Gemma ビルドを探して。」→ search_models { source: "huggingface" }
• 「このテキストから請求書の項目をローカルで JSON として抽出して。」→ delegate { task: "extract", responseFormat: { type: "json_schema", ... } }
• 「Llama 3.1 70B は、ここで 32K のコンテキストサイズで動く？」→ fit_check { model, contextLength: 32768 }

クイックスタート

ランタイム（Ollama、LM Studio、llama.cpp、Docker Model Runner、MLX、vLLM または Foundry Local）を少なくとも 1 つインストールし、サーバーをクライアントに追加します。デフォルトのポートを使用するランタイムでは、設定は不要です。

Claude Code

claude mcp add local-ai -- npx -y @tmhs/local-ai-mcp

Claude Desktop。 最新リリースから.mcpbファイルをダウンロードして開きます。ホストの設定画面が表示され、JSON を編集する必要はありません。または、claude_desktop_config.jsonに次の内容を追加します。

{
  "mcpServers": {
    "local-ai": { "command": "npx", "args": ["-y", "@tmhs/local-ai-mcp"] }
  }
}

Cursor / VS Code。 上記のインストールボタンを使用するか、同じcommand/argsを.cursor/mcp.jsonまたは.vscode/mcp.jsonに追加します（VS Code では"mcpServers"ではなく、トップレベルの"servers"キーを使用します）。

Windsurf、Cline、Zed、その他のクライアント。 stdio MCP クライアントであれば使用できます。コマンドはnpx、引数は["-y", "@tmhs/local-ai-mcp"]です。

Windows： 一部のクライアントではnpxを直接起動できません。サーバーが起動しない場合は、"command": "cmd", "args": ["/c", "npx", "-y", "@tmhs/local-ai-mcp"]を使用してください。

ホステッドプロバイダーの追加（任意）。 サーバーのenvにMOONSHOT_API_KEYを設定します。これは、ツール呼び出しでprovider: "moonshot"が指定された場合にのみ使用されます。ただし、LOCAL_AI_ALLOW_HOSTED_FALLBACK=1も設定している場合は除きます。

対応ランタイム

ランタイム	有効化条件	デフォルトのホスト	一覧表示 / 読み込み済み	ダウンロード	読み込み / 解除	削除	埋め込み	備考
Ollama	常時	localhost:11434	✓ / ✓	✓ 進捗表示	✓ (keep_alive, num_ctx)	✓	✓	ネイティブの/api/chat：contextLengthはnum_ctxを設定し、正確なタイミングと JSON スキーマのformatに対応
LM Studio	常時	localhost:1234	✓ / ✓	✓ lms経由	✓ lms経由（TTL、コンテキスト）	✓ lms経由	✓	ライフサイクル管理にはlms CLIが必要です。これがない場合、モデルは最初のリクエスト時に読み込まれます
llama.cpp（llama-server）	常時	localhost:8080	✓ / ✓ (/slots)	–	–	–	✓	サーバーごとにモデルは 1 つです。embedを使うには--embeddingsを指定して起動します
Docker Model Runner	常時	localhost:12434	✓ / –	✓ 進捗表示	最初のリクエスト時	✓	✓	Docker Desktop でホスト側の TCP サポートを有効にしてください
MLX（mlx_lm.server）	MLX_HOST	–	✓ / –	–	最初のリクエスト時	–	–	Apple Silicon 対応。リクエストごとにモデルを切り替えます
vLLM	VLLM_HOST	–	✓ / ✓	–	–	–	✓	health_checkは/metricsから KV キャッシュの使用状況とキューの深さを報告します
Foundry Local	FOUNDRY_LOCAL_HOST	動的ポート	✓ / ✓	✓ 進捗表示	✓（TTL）	–	–	foundry service statusでポートを確認します
OpenAI 互換（Jan、LocalAI、…）	OPENAI_COMPAT_HOST	–	✓ / ✓	–	–	–	✓	ホストからローカルかホステッドかを判別します
Moonshot AI（Kimi）	MOONSHOT_API_KEY	api.moonshot.ai/v1	✓ / –	–	–	–	–	ホステッド： 暗黙的に選択されることはありません

LOCAL_AI_PROVIDERS='[{"type":"ollama","name":"ollama-gpu2","host":"http://192.168.1.20:11434"}]'を使うと、LAN 上の 2 台目の Ollama マシンなど、同じランタイムを複数起動できます。使用しないランタイムの検出をスキップするには、LOCAL_AI_DISABLE=lmstudio,dockermodelrunnerを使用します。

プライバシーモデル

• 各プロバイダーは ローカル または ホステッド のいずれかです。種別はホストから推定されます。ループバック、プライベート LAN の範囲、*.local、Tailscale CGNAT、host.docker.internal はローカルとして扱われます。LOCAL_AI_PROVIDERS でインスタンスごとに上書きできます。
• provider 引数を指定しない場合、complete、embed、delegate、benchmark、load_model およびその他のモデル単位のツールは、そのモデルを持つ 稼働中のローカル プロバイダーのみを対象とします。モデルがホステッドプロバイダーにしか存在しない場合、呼び出しは失敗し、オプトインの方法が通知されます。
• ホステッドプロバイダーは、通常の呼び出しではプローブされません。接続するのは health_check と diagnostics のみです。
• source: "huggingface" を指定した search_models は Hugging Face Hub に問い合わせます。問い合わせは明示的に要求した場合に限られます。禁止するには LOCAL_AI_DISABLE_NETWORK_SEARCH=1 を設定します。
• サーバーは stdio のみ を使用します。ネットワークリスナーを開くことはありません。

ツール（19）

すべてのツールは MCP アノテーション（読み取り専用、破壊的、オープンワールド）と出力スキーマを宣言し、構造化コンテンツを返します。

グループ	ツール	機能
検出	list_providers	設定済みランタイム：種別（ローカル／ホステッド）、稼働状況、機能
	list_models	稼働中の各プロバイダーにインストールされているモデル
	list_loaded	メモリ上に常駐するモデル。VRAM 使用量とコンテキスト長も表示
	model_info	ファミリー、サイズ、量子化、コンテキスト長、レイヤーアーキテクチャ
ライフサイクル	pull_model	負荷大。 1 つのプロバイダーにダウンロードし、進行状況の通知をストリーミングします。background: true を指定すると、代わりにジョブ ID を返します
	pull_status / pull_cancel	バックグラウンドでのダウンロード状況の確認／停止
	remove_model	破壊的。 provider は必須です。クライアントが対応している場合は MCP のエリシテーションを通じて直接確認を求め、それ以外の場合は confirm: true が必要です
	load_model / unload_model	1 つのプロバイダーに対して実行します。keepAlive と contextLength は任意です
	ensure_model	ダウンロード（許可されている場合）、適合性チェック、他のモデルの退避（lru／all）、読み込み、検証を行います。dryRun は計画のみを返します
運用	health_check	到達可能性、バージョン、ランタイムメトリクス
	diagnostics	有効な設定（キーは伏字）、レイテンシとエラーを含むプロバイダーごとの検出結果、速度キャッシュ、ハードウェアの検出元。バグ報告に貼り付けてください
	system_resources	RAM と GPU（NVIDIA、AMD、Intel、Apple Silicon）。それぞれのデータソースも表示
	fit_check	指定したコンテキスト長と KV キャッシュ精度におけるモデルの状態として、gpu／partial／cpu／none を返します
	benchmark	負荷大。 ウォームアップ後に N 回実行し、最初のトークンまでの時間、生成速度、プロンプトのトークン数／秒を測定します。比較するには models: [...] を指定します
レジストリ	search_available	組み込みのオフラインカタログ
	suggest_model	このマシンでタスクに最適なモデルを提案します。まず GPU に収まる最大のモデルを選び、インストール済みのモデルにはフラグを付けます
	search_models	Hugging Face の GGUF をライブ検索し、量子化ごとの適合性とダウンロード参照（hf.co/<repo>:<quant>）を表示します
委任	complete	選択したモデルで補完を実行します。システムプロンプト、JSON／JSON スキーマ出力（検証済み）、シード、サンプリング、画像、contextLength に対応
	embed	埋め込みを生成します。入力ごとに常に 1 つのベクトルを返します
	delegate	1 回の呼び出し： タスクに最適なローカルモデルを選び（読み込み済み、次にインストール済みかつ適合するもの、必要に応じてダウンロード。大きいサイズのティアを優先し、同じティア内ではこのマシン上の benchmark で測定した速度で順位を決めます）、実行して選択理由を説明します

リソース： local-ai://system、local-ai://loaded（サブスクライブ可能。モデルの読み込みまたはアンロード時に更新）、local-ai://models/{provider}。 プロンプト： setup、free-vram、benchmark-my-models、pick-model。

設定

すべての設定は環境変数で指定し、空欄の場合はデフォルト値が使われます。注釈付きの全項目については、.env.example を参照してください。

変数	デフォルト	用途
OLLAMA_HOST、LMSTUDIO_HOST、LLAMACPP_HOST、DOCKER_MODEL_RUNNER_HOST	標準のローカルポート	常時稼働するランタイム
MLX_HOST、VLLM_HOST（VLLM_API_KEY と併用）、FOUNDRY_LOCAL_HOST、OPENAI_COMPAT_HOST（OPENAI_COMPAT_API_KEY と併用）	未設定	オプトイン方式のランタイム
LOCAL_AI_PROVIDERS	未設定	追加インスタンスの JSON 配列 {type, host, name?, apiKey?, kind?}
LOCAL_AI_DISABLE	未設定	スキップするタイプまたは名前をカンマ区切りで指定
MOONSHOT_API_KEY、MOONSHOT_HOST	未設定、https://api.moonshot.ai/v1	ホスト型 Moonshot プロバイダー
LOCAL_AI_ALLOW_HOSTED_FALLBACK	オフ	provider を指定しない呼び出しで、ホスト型プロバイダーの使用を許可
LOCAL_AI_DISABLE_NETWORK_SEARCH	オフ	Hugging Face の検索を禁止
LOCAL_AI_BENCHMARK_CACHE	ユーザーごとのキャッシュディレクトリ	delegate のランキングに使う benchmark の結果の保存先（14 日後に期限切れ）。off で無効化
LOCAL_AI_REQUEST_TIMEOUT_MS	120000	ストリーミング以外のリクエスト
LOCAL_AI_DETECT_TIMEOUT_MS	1500	検出プローブ
LOCAL_AI_PULL_TIMEOUT_MS	3600000	ダウンロード（0 = 制限なし）
LOCAL_AI_STREAM_IDLE_TIMEOUT_MS	60000	指定時間トークンが届かない場合にのみストリームを中止
LOCAL_AI_STREAM_MAX_MS	1800000	ストリーミング生成の最大時間（0 = なし）
LOCAL_AI_CACHE_TTL_MS	10000	検出とモデル一覧のキャッシュ

トラブルシューティング

• プロバイダーが検出されません。 diagnostics（または health_check）を実行してください。ホストとポートを確認してください。WSL からは Windows ホストの IP アドレスを使います。コンテナーからは host.docker.internal を使います。Docker Model Runner の場合は、ホスト側の TCP サポートを有効にしてください。
• LM Studio のプル／読み込みが「requires the lms CLI」で失敗します。 LM Studio CLI docs の説明に従って lms CLI をインストールし、PATH に通してから、MCP クライアントを再起動してください。
• llama.cpp の embed が失敗します。 --embeddings と埋め込みに対応したモデルを指定して llama-server を起動してください。
• 長い入力に対する回答が途中で切れているように見えます（Ollama）。 contextLength を渡してください（num_ctx が設定されます）。切り詰められている可能性が高い場合、結果に警告が含まれます。
• 「was not found on any live local provider」と表示されます。 モデルがインストールされていないか（list_models で確認してください）、ホスト型プロバイダーでのみ利用できます。使用するには、そのプロバイダーを明示的に指定してください。
• macOS のメモリ値が低く見えます。 system_resources が報告するのは、使用可能なメモリ（空き、非アクティブ、および消去可能なページ）と Metal のワーキングセット上限であり、RAM の合計ではありません。

開発

npm install
npm run build       # tsc -> dist/
npm test            # vitest, fully offline (mocked HTTP, stubbed hardware)
npm run lint        # Biome
npm run typecheck   # src and tests
npm run gen:tools   # regenerate mcp-tools.json after changing tools
npm run smoke       # boot the built server over stdio

CI は、サポートされる最小バージョンの Node 22 と Node 24 を使い、Linux、Windows、macOS で実行されます。毎晩実行されるワークフローでは、実際の Ollama および llama.cpp に対してアダプターをテストします。ランタイムアダプターの追加を含む CONTRIBUTING.md を参照してください。

サポート

質問やアイデアは Discussions に投稿してください。バグは issue テンプレートを使って報告し、セキュリティ上の問題は非公開の報告手段から報告してください。このツールが時間の節約に役立った場合は、スポンサーになることをご検討ください。

ライセンス

CC-BY-NC-ND-4.0。LICENSE を参照してください。コントリビューションは、DCO および CONTRIBUTING.md に記載された受領者への許諾条件に基づいて受け付けています。

---

TMHSDigital が開発