LMStudio-MCP

LMStudio-MCP creates a bridge between Claude (with MCP capabilities) and your locally running LM Studio instance. This allows Claude to:

• Check the health of your LM Studio API
• List available models
• Get the currently loaded model
• Generate chat and raw text completions using your local models
• Generate vector embeddings for semantic search and RAG
• Hold stateful multi-turn conversations via response IDs
• Start and continue persistent conversations with a locked-in system prompt

This enables you to leverage your own locally running models through Claude's interface, combining Claude's capabilities with your private models.

• Python 3.7+
• LM Studio installed and running locally with a model loaded
• Claude with MCP access
• Required Python packages (see Installation)

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

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

# 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

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

For detailed deployment instructions, see DOCKER.md.

The bridge supports flexible configuration for different deployment scenarios:

• Default: Connects to http://localhost:1234/v1
• Custom Host: Set LMSTUDIO_HOST environment variable (e.g., 192.168.1.100)
• Custom Port: Set LMSTUDIO_PORT environment variable (e.g., 5678)

Example:

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

📖 For detailed configuration options, see CONFIGURATION.md

Using GitHub directly (simplest):

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

Using local installation:

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

Using Docker:

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

For complete MCP configuration instructions, see MCP_CONFIGURATION.md.

You can add a description field to your .mcp.json entry to help Claude understand when to use this server and what to expect. This is particularly useful for reminding Claude of version requirements:

{
  "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+."
  }
}

Setting a system prompt directly in LM Studio gives your local model a consistent baseline personality and behaviour across all interactions — without needing to pass it on every API call.

1. Open LM Studio
2. Click the model name at the top of the chat panel
3. Find the System Prompt field (may be under a ⚙️ gear icon or Advanced settings)
4. Paste your system prompt and save

The system prompt set here applies to all completions sent via the API, including those from this MCP bridge.

General assistant — clean and direct:

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

Casual conversation partner:

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.

Local coding assistant:

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.

Privacy-first document analyst:

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

💡 Tip: Always end your system prompt with "Never cut off mid-sentence — always finish your thought." This prevents truncated responses regardless of how max_tokens is configured.

1. Start LM Studio and ensure it's running on port 1234 (the default)
2. Set a system prompt in LM Studio (see above — recommended)
3. Load a model in LM Studio
4. Configure Claude MCP with one of the configurations above
5. Connect to the MCP server in Claude when prompted

The bridge provides the following 9 tools:

The recommended way to run a persistent conversation with a local model:

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..." }

The system prompt is locked in for the entire session — no need to re-send it on every turn. Requires LM Studio v0.3.29+.

This project supports multiple deployment methods:

• Some models (e.g., phi-3.5-mini-instruct_uncensored) may have compatibility issues
• The bridge currently uses only the OpenAI-compatible API endpoints of LM Studio
• Model responses will be limited by the capabilities of your locally loaded model
• create_response, start_conversation, and continue_conversation require LM Studio v0.3.29+
• generate_embeddings requires an embedding-specific model (e.g. text-embedding-nomic-embed-text-v1.5)

If Claude reports 404 errors when trying to connect to LM Studio:

• Ensure LM Studio is running and has a model loaded
• Check that LM Studio's server is running on port 1234
• Verify your firewall isn't blocking the connection
• Try using "127.0.0.1" instead of "localhost" in the API URL if issues persist

If certain models don't work correctly:

• Some models might not fully support the OpenAI chat completions API format
• Try different parameter values (temperature, max_tokens) for problematic models
• Consider switching to a more compatible model if problems persist

For detailed troubleshooting help, see TROUBLESHOOTING.md.

This project includes comprehensive Docker support:

• Multi-architecture images (AMD64, ARM64/Apple Silicon)
• Automated builds via GitHub Actions
• Pre-built images available on GitHub Container Registry
• Docker Compose for easy deployment
• Kubernetes manifests for production deployments

See DOCKER.md for complete containerization documentation.

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

MIT

This project was originally developed as "Claude-LMStudio-Bridge_V2" and has been renamed and open-sourced as "LMStudio-MCP".

Looking for more advanced features? Check out the community-built enhanced version:

• lmstudio-bridge-enhanced by @ahmedibrahim085 — A powerful extension built on top of this project, adding autonomous agent loops, 37 tools, dynamic MCP discovery, multi-model routing, vision support, and much more.

🌟 If this project helps you, please consider giving it a star!