LMStudio-MCP

LMStudio-MCP

Claude が LM Studio 経由でローカルで実行中の LLM モデルと通信できるようにする、モデル制御プロトコル（MCP）サーバーです。

概要

LMStudio-MCP は、Claude（MCP 機能を搭載）と、ローカルで実行中の LM Studio インスタンスをつなぐブリッジを作成します。これにより、Claude は次のことができます。

• LM Studio API の状態を確認する
• 利用可能なモデルを一覧表示する
• 現在読み込まれているモデルを取得する
• ローカルモデルを使用して、チャットおよび生テキストの補完を生成する
• セマンティック検索や RAG 向けのベクトル埋め込みを生成する
• 応答 ID を介して、状態を保持する複数ターンの会話を行う
• システムプロンプトを固定した、継続性のある会話を開始して続ける

これにより、Claude のインターフェースを通じてローカルで実行中の独自モデルを活用し、Claude の機能とプライベートモデルを組み合わせることができます。

前提条件

• Python 3.7+
• LM Studio がインストールされ、モデルを読み込んだ状態でローカル実行されていること
• MCP にアクセスできる Claude
• 必要な Python パッケージ（インストールを参照）

🚀 クイックインストール

1 行でインストール（推奨）

curl -fsSL https://raw.githubusercontent.com/infinitimeless/LMStudio-MCP/main/install.sh | bash

手動インストール方法

1. ローカル Python インストール

git clone https://github.com/infinitimeless/LMStudio-MCP.git
cd LMStudio-MCP
pip install requests "mcp[cli]" openai

2. Docker インストール

# Using pre-built image
docker run -it --network host ghcr.io/infinitimeless/lmstudio-mcp:latest

# Or build locally
git clone https://github.com/infinitimeless/LMStudio-MCP.git
cd LMStudio-MCP
docker build -t lmstudio-mcp .
docker run -it --network host lmstudio-mcp

3. Docker Compose

git clone https://github.com/infinitimeless/LMStudio-MCP.git
cd LMStudio-MCP
docker-compose up -d

詳しいデプロイ手順については、DOCKER.md を参照してください。

⚙️ 設定

このブリッジは、さまざまなデプロイシナリオに対応する柔軟な設定をサポートしています。

• デフォルト：http://localhost:1234/v1 に接続します
• カスタムホスト：LMSTUDIO_HOST 環境変数を設定します（例：192.168.1.100）
• カスタムポート：LMSTUDIO_PORT 環境変数を設定します（例：5678）

例：

export LMSTUDIO_HOST=192.168.1.100
export LMSTUDIO_PORT=5678
python lmstudio_bridge.py

📖 詳しい設定オプションについては、CONFIGURATION.md を参照してください。

MCP の設定

クイックセットアップ

GitHub を直接使用する場合（最も簡単）：

{
  "lmstudio-mcp": {
    "command": "uvx",
    "args": [
      "https://github.com/infinitimeless/LMStudio-MCP"
    ]
  }
}

ローカルインストールを使用する場合：

{
  "lmstudio-mcp": {
    "command": "/bin/bash",
    "args": [
      "-c",
      "cd /path/to/LMStudio-MCP && source venv/bin/activate && python lmstudio_bridge.py"
    ]
  }
}

Docker を使用する場合：

{
  "lmstudio-mcp-docker": {
    "command": "docker",
    "args": [
      "run",
      "-i",
      "--rm",
      "--network=host",
      "ghcr.io/infinitimeless/lmstudio-mcp:latest"
    ]
  }
}

MCP の設定手順について詳しくは、MCP_CONFIGURATION.md を参照してください。

オプション：MCP の description ヒント

.mcp.json のエントリーに description フィールドを追加すると、このサーバーをいつ使用するか、何を期待できるかを Claude が理解しやすくなります。バージョン要件を Claude に思い出させる場合に、特に便利です。

{
  "lmstudio-mcp": {
    "command": "...",
    "args": [...],
    "description": "Local LLM bridge via LM Studio. Use for private/offline inference, embeddings, and multi-turn conversations. start_conversation and continue_conversation require LM Studio v0.3.29+."
  }
}

🧠 LM Studio のシステムプロンプト（推奨）

LM Studio にシステムプロンプトを直接設定すると、API 呼び出しのたびに渡さなくても、ローカルモデルはすべてのやり取りで一貫した基本的な人格と振る舞いを保てます。

設定方法

1. LM Studio を開きます
2. チャットパネル上部にあるモデル名をクリックします
3. System Prompt フィールドを見つけます（⚙️ 歯車アイコンまたは Advanced settings の中にある場合があります）
4. システムプロンプトを貼り付けて保存します

ここで設定したシステムプロンプトは、この MCP ブリッジからのものを含め、API 経由で送信されるすべての補完に適用されます。

システムプロンプトの例

一般的なアシスタント — 簡潔で率直：

You are a helpful, concise assistant. Answer directly without preamble like
"Sure!" or "Of course!". Never cut off mid-sentence — always finish your thought.

気軽な会話相手：

You are a regular person having a relaxed conversation with a friend.
Keep responses short and natural, like real chat. No bullet points or formal
language. You can invent fun details about your life and stay consistent with them.
Never cut off mid-sentence — always finish your thought.

ローカルのコーディングアシスタント：

You are an expert software engineer. Be concise and precise. When writing code,
always include brief inline comments. Prefer simple, readable solutions over
clever ones. Never cut off mid-sentence or mid-code block.

プライバシー優先の文書分析担当：

You are a careful document analyst. Summarise accurately and concisely.
Never invent information not present in the source material.
Always flag uncertainty explicitly.

💡 ヒント： システムプロンプトの末尾には、必ず「Never cut off mid-sentence — always finish your thought.」を付けてください。これにより、max_tokens の設定に関係なく、応答が途中で切れるのを防げます。

使用方法

1. LM Studio を起動し、ポート 1234（デフォルト）で実行中であることを確認します
2. LM Studio にシステムプロンプトを設定します（上記を参照 — 推奨）
3. LM Studio でモデルを読み込みます
4. 上記のいずれかの設定で Claude MCP を設定します
5. プロンプトが表示されたら、Claude で MCP サーバーに接続します

利用可能なツール

ブリッジでは、次の 9 つのツールを利用できます。

ツール	説明
health_check()	LM Studio API にアクセスできるか確認します
list_models()	LM Studio で利用可能なすべてのモデルの一覧を取得します
get_current_model()	現在読み込まれているモデルを特定します
chat_completion(prompt, system_prompt, temperature, max_tokens)	ローカルモデルからチャット応答を生成します
text_completion(prompt, temperature, max_tokens, stop_sequences)	生のテキスト／コード補完を生成します。チャット形式のオーバーヘッドがないため高速です
generate_embeddings(text, model)	セマンティック検索や RAG ワークフロー用のベクトル埋め込みを生成します
create_response(input_text, previous_response_id, reasoning_effort, stream, model)	応答 ID を使った状態保持型の会話です。LM Studio v0.3.29 以降が必要です
start_conversation(system_prompt, first_message, temperature, max_tokens, model)	システムプロンプトを維持する複数ターンのセッションを開始し、response_id を返します
continue_conversation(response_id, message, temperature, max_tokens, model)	start_conversation で開始したセッションを続行します。コンテキストは自動的に保持されます

複数ターンの会話ワークフロー

ローカルモデルとの継続的な会話を実行するための推奨方法です。

1. start_conversation(
     system_prompt="You are a friend at a bar, keep it casual and fun.",
     first_message="Hey! How's it going?"
   )
   → { response_id: "resp_abc...", message: "Hey! Not bad, just unwinding..." }

2. continue_conversation(
     response_id="resp_abc...",
     message="Work's been insane this week."
   )
   → { response_id: "resp_def...", message: "Ugh, tell me about it..." }

3. continue_conversation(
     response_id="resp_def...",
     message="If you could go anywhere tomorrow, where would you go?"
   )
   → { response_id: "resp_ghi...", message: "Honestly? Northern Portugal..." }

システムプロンプトはセッション全体で固定されるため、ターンごとに再送信する必要はありません。 LM Studio v0.3.29 以降が必要です。

デプロイ方法

このプロジェクトでは、複数のデプロイ方法をサポートしています。

方法	用途	メリット	デメリット
Local Python	開発、簡単なセットアップ	高速、直接制御可能	Python のセットアップが必要
Docker	分離された環境	クリーンで移植性が高い	Docker が必要
Docker Compose	本番環境へのデプロイ	管理が簡単	セットアップがより複雑
Kubernetes	エンタープライズ／大規模運用	高いスケーラビリティ	設定が複雑
GitHub Direct	セットアップ不要	ローカルへのインストールが不要	インターネット接続が必要

既知の制限事項

• 一部のモデル（例：phi-3.5-mini-instruct_uncensored）では、互換性の問題が発生する場合があります
• このブリッジは現在、LM Studio の OpenAI 互換 API エンドポイントのみを使用します
• モデルの応答は、ローカルで読み込まれているモデルの能力に制限されます
• create_response、start_conversation、continue_conversation には LM Studio v0.3.29 以降が必要です
• generate_embeddings には、埋め込み専用モデル（例：text-embedding-nomic-embed-text-v1.5）が必要です

トラブルシューティング

API 接続の問題

LM Studio への接続時に Claude が 404 エラーを報告する場合：

• LM Studio が起動しており、モデルが読み込まれていることを確認してください
• LM Studio のサーバーがポート 1234 で実行されていることを確認してください
• ファイアウォールが接続をブロックしていないことを確認してください
• 問題が解決しない場合は、API URL の「localhost」の代わりに「127.0.0.1」を使用してみてください

モデルの互換性

特定のモデルが正しく動作しない場合：

• 一部のモデルは OpenAI チャット補完 API 形式を完全にはサポートしていない可能性があります
• 問題が発生するモデルでは、異なるパラメーター値（temperature、max_tokens）を試してください
• 問題が解決しない場合は、より互換性の高いモデルへの切り替えを検討してください

詳しいトラブルシューティングについては、TROUBLESHOOTING.md を参照してください。

🐳 Docker とコンテナ化

このプロジェクトは、包括的な Docker サポートを備えています。

• マルチアーキテクチャイメージ（AMD64、ARM64／Apple Silicon）
• GitHub Actions による自動ビルド
• GitHub Container Registry で利用可能なビルド済みイメージ
• 簡単にデプロイできる Docker Compose
• 本番環境へのデプロイ用 Kubernetes マニフェスト

コンテナ化に関する詳細なドキュメントは、DOCKER.md を参照してください。

貢献

貢献を歓迎します！ガイドラインについては、CONTRIBUTING.md を参照してください。

ライセンス

MIT

謝辞

このプロジェクトは当初「Claude-LMStudio-Bridge_V2」として開発され、 名称を変更して「LMStudio-MCP」としてオープンソース化されました。

コミュニティプロジェクト

より高度な機能をお探しですか？コミュニティが開発した強化版をご覧ください。

• lmstudio-bridge-enhanced @ahmedibrahim085 によるプロジェクトです。本プロジェクトをベースに構築された強力な拡張機能で、自律型エージェントループ、37 個のツール、動的な MCP の検出、マルチモデルルーティング、ビジョンサポートなど、さまざまな機能を追加します。

---

🌟 このプロジェクトがお役に立った場合は、ぜひスターを付けてください！