LMStudio-MCP

Un servidor de Protocolo de Control de Modelos (MCP) que permite a Claude comunicarse con modelos LLM que se ejecutan localmente a través de LM Studio.

Descripción general

LMStudio-MCP crea un puente entre Claude (con capacidades MCP) y tu instancia de LM Studio ejecutándose localmente. Esto permite a Claude:

• Comprobar el estado de tu API de LM Studio

• Listar los modelos disponibles

• Obtener el modelo cargado actualmente

• Generar chats y completaciones de texto sin formato utilizando tus modelos locales

• Generar incrustaciones (embeddings) vectoriales para búsqueda semántica y RAG

• Mantener conversaciones con estado de varios turnos mediante IDs de respuesta

• Iniciar y continuar conversaciones persistentes con un prompt del sistema bloqueado

Esto te permite aprovechar tus propios modelos ejecutándose localmente a través de la interfaz de Claude, combinando las capacidades de Claude con tus modelos privados.

Related MCP server: Ollama MCP Server

Requisitos previos

• Python 3.7+

• LM Studio instalado y ejecutándose localmente con un modelo cargado

• Claude con acceso a MCP

• Paquetes de Python necesarios (ver Instalación)

🚀 Instalación rápida

Instalación en una línea (Recomendado)

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

Métodos de instalación manual

1. Instalación local de Python

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

2. Instalación con 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

Para obtener instrucciones detalladas de despliegue, consulta DOCKER.md.

⚙️ Configuración

El puente admite una configuración flexible para diferentes escenarios de despliegue:

• Predeterminado: Se conecta a http://localhost:1234/v1

• Host personalizado: Establece la variable de entorno LMSTUDIO_HOST (p. ej., 192.168.1.100)

• Puerto personalizado: Establece la variable de entorno LMSTUDIO_PORT (p. ej., 5678)

Ejemplo:

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

📖 Para opciones de configuración detalladas, consulta CONFIGURATION.md

Configuración de MCP

Configuración rápida

Usando GitHub directamente (lo más sencillo):

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

Usando instalación local:

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

Usando Docker:

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

Para obtener instrucciones completas de configuración de MCP, consulta MCP_CONFIGURATION.md.

Opcional: Sugerencia de description para MCP

Puedes añadir un campo description a tu entrada en .mcp.json para ayudar a Claude a entender cuándo usar este servidor y qué esperar. Esto es especialmente útil para recordar a Claude los requisitos de versión:

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

🧠 Prompt del sistema de LM Studio (Recomendado)

Establecer un prompt del sistema directamente en LM Studio le da a tu modelo local una personalidad y un comportamiento base consistentes en todas las interacciones, sin necesidad de pasarlo en cada llamada a la API.

Cómo configurarlo

1. Abre LM Studio

2. Haz clic en el nombre del modelo en la parte superior del panel de chat

3. Busca el campo System Prompt (puede estar bajo un icono de engranaje ⚙️ o en Advanced settings)

4. Pega tu prompt del sistema y guarda

El prompt del sistema establecido aquí se aplica a todas las completaciones enviadas a través de la API, incluidas las de este puente MCP.

Ejemplos de prompts del sistema

Asistente general — limpio y directo:

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

Compañero de conversación informal:

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.

Asistente de programación local:

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.

Analista de documentos centrado en la privacidad:

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

💡 Consejo: Termina siempre tu prompt del sistema con "Never cut off mid-sentence — always finish your thought." (Nunca cortes a mitad de frase, termina siempre tu pensamiento). Esto evita respuestas truncadas independientemente de cómo esté configurado max_tokens.

Uso

1. Inicia LM Studio y asegúrate de que se esté ejecutando en el puerto 1234 (el predeterminado)

2. Establece un prompt del sistema en LM Studio (ver arriba, recomendado)

3. Carga un modelo en LM Studio

4. Configura Claude MCP con una de las configuraciones anteriores

5. Conéctate al servidor MCP en Claude cuando se te solicite

Herramientas disponibles

El puente proporciona las siguientes 9 herramientas:

Flujo de trabajo de conversación de varios turnos

La forma recomendada de ejecutar una conversación persistente con un modelo local:

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

El prompt del sistema queda bloqueado durante toda la sesión; no es necesario volver a enviarlo en cada turno. Requiere LM Studio v0.3.29+.

Opciones de despliegue

Este proyecto admite múltiples métodos de despliegue:

Limitaciones conocidas

• Algunos modelos (p. ej., phi-3.5-mini-instruct_uncensored) pueden tener problemas de compatibilidad

• El puente utiliza actualmente solo los endpoints de la API compatibles con OpenAI de LM Studio

• Las respuestas del modelo estarán limitadas por las capacidades de tu modelo cargado localmente

• create_response, start_conversation y continue_conversation requieren LM Studio v0.3.29+

• generate_embeddings requiere un modelo específico de incrustación (p. ej., text-embedding-nomic-embed-text-v1.5)

Solución de problemas

Problemas de conexión a la API

Si Claude informa de errores 404 al intentar conectarse a LM Studio:

• Asegúrate de que LM Studio se esté ejecutando y tenga un modelo cargado

• Comprueba que el servidor de LM Studio se esté ejecutando en el puerto 1234

• Verifica que tu firewall no esté bloqueando la conexión

• Intenta usar "127.0.0.1" en lugar de "localhost" en la URL de la API si los problemas persisten

Compatibilidad de modelos

Si ciertos modelos no funcionan correctamente:

• Algunos modelos podrían no ser totalmente compatibles con el formato de la API de completaciones de chat de OpenAI

• Prueba diferentes valores de parámetros (temperature, max_tokens) para modelos problemáticos

• Considera cambiar a un modelo más compatible si los problemas persisten

Para obtener ayuda detallada sobre la solución de problemas, consulta TROUBLESHOOTING.md.

🐳 Docker y contenedorización

Este proyecto incluye soporte integral para Docker:

• Imágenes multiarquitectura (AMD64, ARM64/Apple Silicon)

• Compilaciones automatizadas mediante GitHub Actions

• Imágenes precompiladas disponibles en GitHub Container Registry

• Docker Compose para un despliegue sencillo

• Manifiestos de Kubernetes para despliegues en producción

Consulta DOCKER.md para obtener la documentación completa sobre contenedorización.

Contribuciones

¡Las contribuciones son bienvenidas! Consulta CONTRIBUTING.md para conocer las directrices.

Licencia

MIT

Agradecimientos

Este proyecto se desarrolló originalmente como "Claude-LMStudio-Bridge_V2" y ha sido renombrado y publicado como código abierto bajo el nombre "LMStudio-MCP".

Proyectos de la comunidad

¿Buscas funciones más avanzadas? Echa un vistazo a la versión mejorada creada por la comunidad:

• lmstudio-bridge-enhanced por @ahmedibrahim085 — Una potente extensión construida sobre este proyecto, que añade bucles de agentes autónomos, 37 herramientas, descubrimiento dinámico de MCP, enrutamiento de múltiples modelos, soporte de visión y mucho más.

🌟 Si este proyecto te ayuda, ¡considera darle una estrella!