Skip to content
Back to search

LMStudio-MCP

A Model Control Protocol (MCP) server that allows Claude to communicate with locally running LLM models via LM Studio.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/infinitimeless--lmstudio-mcp/badge.svg)](/listings/infinitimeless--lmstudio-mcp)

HTML

<a href="/listings/infinitimeless--lmstudio-mcp"><img src="/api/listings/infinitimeless--lmstudio-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

One-Line Install (Recommended)

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

Manual Installation Methods

1. Local Python Installation

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

2. Docker Installation

# 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

For detailed deployment instructions, see [DOCKER.md](DOCKER.md).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 314 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # LMStudio-MCP
  2. A Model Control Protocol (MCP) server that allows Claude to communicate with locally running LLM models via LM Studio.
  3. <img width="1881" alt="Screenshot 2025-03-22 at 16 50 53" src="https://github.com/user-attachments/assets/c203513b-28db-4be5-8c61-ebb8a24404ce" />
  4. ## Overview
  5. LMStudio-MCP creates a bridge between Claude (with MCP capabilities) and your locally running LM Studio instance. This allows Claude to:
  6. - Check the health of your LM Studio API
  7. - List available models
  8. - Get the currently loaded model
  9. - Generate chat and raw text completions using your local models
  10. - Generate vector embeddings for semantic search and RAG
  11. - Hold stateful multi-turn conversations via response IDs
  12. - Start and continue persistent conversations with a locked-in system prompt
  13. This enables you to leverage your own locally running models through Claude's interface, combining Claude's capabilities with your private models.
  14. ## Prerequisites
  15. - Python 3.7+
  16. - [LM Studio](https://lmstudio.ai/) installed and running locally with a model loaded
  17. - Claude with MCP access
  18. - Required Python packages (see Installation)
  19. ## 🚀 Quick Installation
  20. ### One-Line Install (Recommended)
  21. ```bash
  22. curl -fsSL https://raw.githubusercontent.com/infinitimeless/LMStudio-MCP/main/install.sh | bash
  23. ```
  24. ### Manual Installation Methods
  25. #### 1. Local Python Installation
  26. ```bash
  27. git clone https://github.com/infinitimeless/LMStudio-MCP.git
  28. cd LMStudio-MCP
  29. pip install requests "mcp[cli]>=1.2,<2" openai
  30. ```
  31. #### 2. Docker Installation
  32. ```bash
  33. # Using pre-built image
  34. docker run -it --network host ghcr.io/infinitimeless/lmstudio-mcp:latest
  35. # Or build locally
  36. git clone https://github.com/infinitimeless/LMStudio-MCP.git
  37. cd LMStudio-MCP
  38. docker build -t lmstudio-mcp .
  39. docker run -it --network host lmstudio-mcp
  40. ```
  41. #### 3. Docker Compose
  42. ```bash
  43. git clone https://github.com/infinitimeless/LMStudio-MCP.git
  44. cd LMStudio-MCP
  45. docker-compose up -d
  46. ```
  47. For detailed deployment instructions, see [DOCKER.md](DOCKER.md).
  48. ## ⚙️ Configuration
  49. The bridge supports flexible configuration for different deployment scenarios:
  50. - **Default**: Connects to `http://localhost:1234/v1`
  51. - **Custom Host**: Set `LMSTUDIO_HOST` environment variable (e.g., `192.168.1.100`)
  52. - **Custom Port**: Set `LMSTUDIO_PORT` environment variable (e.g., `5678`)
  53. Example:
  54. ```bash
  55. export LMSTUDIO_HOST=192.168.1.100
  56. export LMSTUDIO_PORT=5678
  57. python lmstudio_bridge.py
  58. ```
  59. 📖 **For detailed configuration options**, see [CONFIGURATION.md](CONFIGURATION.md)
  60. ## MCP Configuration
  61. ### Quick Setup
  62. **Using GitHub directly (simplest)**:
  63. ```json
  64. {
  65. "lmstudio-mcp": {
  66. "command": "uvx",
  67. "args": [
  68. "https://github.com/infinitimeless/LMStudio-MCP"
  69. ]
  70. }
  71. }
  72. ```
  73. **Using local installation**:
  74. ```json
  75. {
  76. "lmstudio-mcp": {
  77. "command": "/bin/bash",
  78. "args": [
  79. "-c",
  80. "cd /path/to/LMStudio-MCP && source venv/bin/activate && python lmstudio_bridge.py"
  81. ]
  82. }
  83. }
  84. ```
  85. **Using Docker**:
  86. ```json
  87. {
  88. "lmstudio-mcp-docker": {
  89. "command": "docker",
  90. "args": [
  91. "run",
  92. "-i",
  93. "--rm",
  94. "--network=host",
  95. "ghcr.io/infinitimeless/lmstudio-mcp:latest"
  96. ]
  97. }
  98. }
  99. ```
  100. For complete MCP configuration instructions, see [MCP_CONFIGURATION.md](MCP_CONFIGURATION.md).
  101. ### Optional: MCP `description` hint
  102. 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:
  103. ```json
  104. {
  105. "lmstudio-mcp": {
  106. "command": "...",
  107. "args": [...],
  108. "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+."
  109. }
  110. }
  111. ```
  112. ## 🧠 LM Studio System Prompt (Recommended)
  113. 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.
  114. ### How to set it
  115. 1. Open **LM Studio**
  116. 2. Click the model name at the top of the chat panel
  117. 3. Find the **System Prompt** field (may be under a ⚙️ gear icon or **Advanced settings**)
  118. 4. Paste your system prompt and save
  119. > The system prompt set here applies to all completions sent via the API, including those from this MCP bridge.
  120. ### Example system prompts
  121. **General assistant — clean and direct:**
  122. ```
  123. You are a helpful, concise assistant. Answer directly without preamble like
  124. "Sure!" or "Of course!". Never cut off mid-sentence — always finish your thought.
  125. ```
  126. **Casual conversation partner:**
  127. ```
  128. You are a regular person having a relaxed conversation with a friend.
  129. Keep responses short and natural, like real chat. No bullet points or formal
  130. language. You can invent fun details about your life and stay consistent with them.
  131. Never cut off mid-sentence — always finish your thought.
  132. ```
  133. **Local coding assistant:**
  134. ```
  135. You are an expert software engineer. Be concise and precise. When writing code,
  136. always include brief inline comments. Prefer simple, readable solutions over
  137. clever ones. Never cut off mid-sentence or mid-code block.
  138. ```
  139. **Privacy-first document analyst:**
  140. ```
  141. You are a careful document analyst. Summarise accurately and concisely.
  142. Never invent information not present in the source material.
  143. Always flag uncertainty explicitly.
  144. ```
  145. > 💡 **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.
  146. ## Usage
  147. 1. **Start LM Studio** and ensure it's running on port 1234 (the default)
  148. 2. **Set a system prompt** in LM Studio (see above — recommended)
  149. 3. **Load a model** in LM Studio
  150. 4. **Configure Claude MCP** with one of the configurations above
  151. 5. **Connect to the MCP server** in Claude when prompted
  152. ## Available Tools
  153. The bridge provides the following 9 tools:
  154. | Tool | Description |
  155. |------|-------------|
  156. | `health_check()` | Verify if LM Studio API is accessible |
  157. | `list_models()` | Get a list of all available models in LM Studio |
  158. | `get_current_model()` | Identify which model is currently loaded |
  159. | `chat_completion(prompt, system_prompt, temperature, max_tokens)` | Generate a chat response from your local model |
  160. | `text_completion(prompt, temperature, max_tokens, stop_sequences)` | Generate raw text/code completion — faster, no chat formatting overhead |
  161. | `generate_embeddings(text, model)` | Generate vector embeddings for semantic search and RAG workflows |
  162. | `create_response(input_text, previous_response_id, reasoning_effort, stream, model)` | Stateful conversation via response IDs — requires LM Studio v0.3.29+ |
  163. | `start_conversation(system_prompt, first_message, temperature, max_tokens, model)` | Start a multi-turn session with a persistent system prompt — returns a `response_id` |
  164. | `continue_conversation(response_id, message, temperature, max_tokens, model)` | Continue a session started with `start_conversation` — context preserved automatically |
  165. ### Multi-turn conversation workflow
  166. The recommended way to run a persistent conversation with a local model:
  167. ```
  168. 1. start_conversation(
  169. system_prompt="You are a friend at a bar, keep it casual and fun.",
  170. first_message="Hey! How's it going?"
  171. )
  172. → { response_id: "resp_abc...", message: "Hey! Not bad, just unwinding..." }
  173. 2. continue_conversation(
  174. response_id="resp_abc...",
  175. message="Work's been insane this week."
  176. )
  177. → { response_id: "resp_def...", message: "Ugh, tell me about it..." }
  178. 3. continue_conversation(
  179. response_id="resp_def...",
  180. message="If you could go anywhere tomorrow, where would you go?"
  181. )
  182. → { response_id: "resp_ghi...", message: "Honestly? Northern Portugal..." }
  183. ```
  184. > The system prompt is locked in for the entire session — no need to re-send it on every turn.
  185. > Requires LM Studio v0.3.29+.
  186. ## Deployment Options
  187. This project supports multiple deployment methods:
  188. | Method | Use Case | Pros | Cons |
  189. |--------|----------|------|------|
  190. | **Local Python** | Development, simple setup | Fast, direct control | Requires Python setup |
  191. | **Docker** | Isolated environments | Clean, portable | Requires Docker |
  192. | **Docker Compose** | Production deployments | Easy management | More complex setup |
  193. | **Kubernetes** | Enterprise/scale | Highly scalable | Complex configuration |
  194. | **GitHub Direct** | Zero setup | No local install needed | Requires internet |
  195. ## Known Limitations
  196. - Some models (e.g., phi-3.5-mini-instruct_uncensored) may have compatibility issues
  197. - The bridge currently uses only the OpenAI-compatible API endpoints of LM Studio
  198. - Model responses will be limited by the capabilities of your locally loaded model
  199. - `create_response`, `start_conversation`, and `continue_conversation` require LM Studio v0.3.29+
  200. - `generate_embeddings` requires an embedding-specific model (e.g. `text-embedding-nomic-embed-text-v1.5`)
  201. ## Troubleshooting
  202. ### API Connection Issues
  203. If Claude reports 404 errors when trying to connect to LM Studio:
  204. - Ensure LM Studio is running and has a model loaded
  205. - Check that LM Studio's server is running on port 1234
  206. - Verify your firewall isn't blocking the connection
  207. - Try using "127.0.0.1" instead of "localhost" in the API URL if issues persist
  208. ### Model Compatibility
  209. If certain models don't work correctly:
  210. - Some models might not fully support the OpenAI chat completions API format
  211. - Try different parameter values (temperature, max_tokens) for problematic models
  212. - Consider switching to a more compatible model if problems persist
  213. For detailed troubleshooting help, see [TROUBLESHOOTING.md](TROUBLESHOOTING.md).
  214. ## 🐳 Docker & Containerization
  215. This project includes comprehensive Docker support:
  216. - **Multi-architecture images** (AMD64, ARM64/Apple Silicon)
  217. - **Automated builds** via GitHub Actions
  218. - **Pre-built images** available on GitHub Container Registry
  219. - **Docker Compose** for easy deployment
  220. - **Kubernetes manifests** for production deployments
  221. See [DOCKER.md](DOCKER.md) for complete containerization documentation.
  222. ## Contributing
  223. Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
  224. ## License
  225. MIT
  226. ## Acknowledgements
  227. This project was originally developed as "Claude-LMStudio-Bridge_V2" and has been
  228. renamed and open-sourced as "LMStudio-MCP".
  229. ### Community Projects
  230. Looking for more advanced features? Check out the community-built enhanced version:
  231. - **[lmstudio-bridge-enhanced](https://github.com/ahmedibrahim085/lmstudio-bridge-enhanced)**
  232. by [@ahmedibrahim085](https://github.com/ahmedibrahim085) — A powerful extension built
  233. on top of this project, adding autonomous agent loops, 37 tools, dynamic MCP discovery,
  234. multi-model routing, vision support, and much more.
  235. ---
  236. **🌟 If this project helps you, please consider giving it a star!**

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.