local-genai-mcp

LAN内で動いているローカル生成AIを、Claude Code から使えるようにするMCPサーバです。

• Ollama(ローカルLLM): モデル一覧、文章生成

• Stable Diffusion WebUI Forge Neo(WebUI1111互換API): チェックポイント・LoRA・サンプラーの一覧、画像生成(txt2img)

Claude Code に「Ollamaの gemma3:12b でこの文章を要約して」「Forge Neoで夕焼けの海辺の猫を1枚描いて」のように頼むと、このMCPサーバ経由で各サービスを呼び出します。

構成の例

[Ubuntu] Claude Code ──(stdio)── local-genai-mcp ──(HTTP)──┬─ [Windows] Ollama     :11434
                                                            └─ [Windows] Forge Neo  :7860

MCPサーバは Claude Code と同じマシンで動き、Ollama や Forge Neo へは LAN 越しに HTTP でアクセスします。生成した画像は、MCPサーバ側のマシンのフォルダ(既定では ~/ai-studio/repo/genai-outputs/forge)に保存されます。

Related MCP server: Ollama MCP Server

使えるツール

forge_txt2img のプロンプトには、WebUI1111 と同じ書き方((word:1.2) の強調、<lora:名前:重み>)が使えます。

画像の大きさは、width x height(既定 1024x1024)で描いてから、Hires.fix で hr_scale 倍(既定 2倍、ESRGAN_4x)に拡大して描き直します。既定値は config.toml の [forge.defaults] で変えられ、Claude Code に「縦長で」「Hires.fixなしで」「1.5倍で」のように頼めば、1回ごとの指定もできます。

checkpoint を指定すると、Forge Neo 側で選ばれているモデルも切り替わったままになります(続けて同じモデルで生成するときに、読み込み直しを避けるため)。

使い方のヘルプ

使い方と頼み方の例(現在の既定値入り)は、次のどれかで確認できます。

• Claude Code の会話中に /mcp__local-genai__help と入力する(MCP のプロンプト機能。/ を入力すると候補に出る)

• Claude Code に「local-genai の使い方を教えて」と頼む(usage_guide ツールが使われる)

• ターミナルで local-genai-mcp --guide を実行する(下の「うまく動かないとき」のコマンドの --check を --guide に変える)

必要なもの

• Claude Code を使うマシン: Linux(Ubuntu で確認)。Python は uv が自動で用意します

• Ollama 側: 環境変数 OLLAMA_HOST=0.0.0.0:11434 を設定して起動(別のマシンから使う場合)

• Forge Neo 側: webui-user.bat の COMMANDLINE_ARGS に --api --listen を付けて起動

• Windows 側のファイアウォールで、各ポート(11434、7860 など)への接続を許可

セットアップ

cd ~/ai-studio/repo/local-genai-mcp
./install.sh

install.sh が行うこと:

1. uv がなければ、確認のうえ公式スクリプトでインストール

2. 依存ライブラリのインストール(仮想環境は ~/.local/share/local-genai-mcp/venv。このフォルダが NAS 上にあっても、仮想環境はローカルのディスクに置く)

3. config.toml がなければ config.example.toml からコピー

4. config.toml があれば接続確認(--check)

5. Claude Code に local-genai という名前で登録(既定は --scope user = どのフォルダで起動した Claude Code からも使える)

初回は config.toml が作られた時点で、書き換えを促すメッセージが出ます。config.toml を編集してから、接続確認をしてください。

UV_PROJECT_ENVIRONMENT=~/.local/share/local-genai-mcp/venv uv run --project . --no-dev local-genai-mcp --check

主なオプション(./install.sh --help で一覧):

• --no-register: 依存関係の準備と接続確認だけ行い、Claude Code には登録しない

• --dry-run: 実行するコマンドを表示するだけ

• --scope project: 今いるフォルダの .mcp.json に登録する(そのフォルダで起動したときだけ使える)

登録できたかは、Claude Code を起動し直して、会話中に /mcp と入力すると確認できます。

設定ファイル(config.toml)

config.example.toml に説明付きで全項目があります。主な項目:

[ollama]
base_url = "http://192.168.0.10:11434"   # Ollama のアドレス
default_model = "qwen3.5:9b"             # モデル名を省略したときに使う
think = false                            # 思考対応モデルで考える過程を使うか(使うと遅い)

[forge]
base_url = "http://192.168.0.20:7860"    # Forge Neo のアドレス
output_dir = "~/ai-studio/repo/genai-outputs/forge"   # 画像の保存先
preview = true                           # 縮小プレビューを Claude に返すか

[forge.defaults]                         # 画像生成の既定値
width = 1024
height = 1024
steps = 25
cfg_scale = 7.0
sampler_name = "Euler a"
enable_hr = true                         # Hires.fix を使うか
hr_scale = 2.0                           # Hires.fix の倍率
hr_upscaler = "ESRGAN_4x"                # アップスケーラ(forge_list_samplers で確認)
denoising_strength = 0.4                 # 描き直す強さ

• 使わないサービスは enabled = false にすると、そのツール自体が表示されなくなります

• Forge Neo を --api-auth ユーザー名:パスワード 付きで起動している場合は username / password を設定します

• config.toml には実際のアドレスや認証情報が入るので、Git の管理対象外にしています(.gitignore)

• 設定ファイルは、環境変数 LOCAL_GENAI_MCP_CONFIG → このフォルダの config.toml → ~/.config/local-genai-mcp/config.toml の順に探します(local-genai-mcp --print-config-paths で確認できます)

• 設定を書き換えたら、Claude Code を起動し直すと反映されます

登録の解除

./uninstall.sh                 # Claude Code への登録を解除
./uninstall.sh --remove-venv   # 仮想環境も削除(config.toml は残す)

うまく動かないとき

まず接続確認を実行すると、つながらない理由が表示されます。

UV_PROJECT_ENVIRONMENT=~/.local/share/local-genai-mcp/venv uv run --project . --no-dev local-genai-mcp --check

• Ollama に接続できない: Ollama 側で OLLAMA_HOST=0.0.0.0:11434 を設定して起動し直したか、ファイアウォールで 11434 番を許可したか

• Forge Neo に接続できない: --listen を付けたか、ファイアウォールで 7860 番(--port で変えた場合はその番号)を許可したか

• Forge Neo の /sdapi/... が 404: --api を付け忘れている

• 認証エラー(401): --api-auth を使っている場合は config.toml の username / password

• 画像生成がタイムアウトする: config.toml の [forge] の timeout_seconds を増やす(大きいモデルの初回読み込みは時間がかかる)

• 接続の確立は5秒で打ち切るので、アドレスの間違いなどはすぐに分かります

開発

uv sync                # 開発用(pytest)も含めてインストール
uv run pytest          # テスト(実際の Ollama / Forge Neo は不要。HTTP の応答を模擬している)

MCP の Python SDK は 2.x 系を使っています(mcp.server.mcpserver.MCPServer)。1.x 系の FastMCP とは書き方が異なります。

未対応・今後の候補

• img2img、ComfyUI、音声合成(Irodori-TTS)などは未対応

ライセンス

MIT License(LICENSE を参照)。依存ライブラリ(mcp: MIT、httpx: BSD-3-Clause、Pillow: MIT-CMU ほか)はいずれも MIT と両立する許諾条件で、このリポジトリには同梱していません(インストール時に uv が取得します)。