LMStudio-MCP

Сервер протокола управления моделями (MCP), который позволяет Claude взаимодействовать с локально запущенными моделями LLM через LM Studio.

Обзор

LMStudio-MCP создает мост между Claude (с поддержкой MCP) и вашим локально запущенным экземпляром LM Studio. Это позволяет Claude:

• Проверять работоспособность API LM Studio

• Получать список доступных моделей

• Получать информацию о текущей загруженной модели

• Генерировать ответы в чате и дополнения текста с использованием ваших локальных моделей

• Генерировать векторные эмбеддинги для семантического поиска и RAG

• Вести диалоги с сохранением состояния через ID ответов

• Начинать и продолжать постоянные диалоги с зафиксированным системным промптом

Это позволяет вам использовать собственные локальные модели через интерфейс Claude, объединяя возможности Claude с вашими приватными моделями.

Related MCP server: Ollama MCP Server

Предварительные требования

• Python 3.7+

• LM Studio, установленный и запущенный локально с загруженной моделью

• Claude с доступом к MCP

• Необходимые пакеты Python (см. раздел «Установка»)

🚀 Быстрая установка

Установка одной командой (рекомендуется)

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.

Дополнительно: подсказка description для MCP

Вы можете добавить поле description в запись .mcp.json, чтобы помочь 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. Вставьте свой системный промпт и сохраните

Установленный здесь системный промпт применяется ко всем дополнениям, отправляемым через API, включая те, что идут через этот MCP-мост.

Примеры системных промптов

Общий ассистент — лаконичный и прямой:

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. Подключитесь к MCP-серверу в Claude при появлении запроса

Доступные инструменты

Мост предоставляет следующие 9 инструментов:

Рабочий процесс диалога с несколькими репликами

Рекомендуемый способ ведения постоянного диалога с локальной моделью:

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+.

Варианты развертывания

Этот проект поддерживает несколько методов развертывания:

Известные ограничения

• Некоторые модели (например, phi-3.5-mini-instruct_uncensored) могут иметь проблемы с совместимостью

• В настоящее время мост использует только API-эндпоинты LM Studio, совместимые с OpenAI

• Ответы моделей будут ограничены возможностями вашей локально загруженной модели

• create_response, start_conversation и continue_conversation требуют LM Studio v0.3.29+

• generate_embeddings требует модель, предназначенную для эмбеддингов (например, text-embedding-nomic-embed-text-v1.5)

Устранение неполадок

Проблемы с подключением к API

Если Claude сообщает об ошибках 404 при попытке подключения к LM Studio:

• Убедитесь, что LM Studio запущен и в нем загружена модель

• Проверьте, что сервер LM Studio запущен на порту 1234

• Убедитесь, что ваш брандмауэр не блокирует соединение

• Попробуйте использовать "127.0.0.1" вместо "localhost" в URL API, если проблемы сохраняются

Совместимость моделей

Если некоторые модели работают некорректно:

• Некоторые модели могут не полностью поддерживать формат API чат-комплитов OpenAI

• Попробуйте изменить значения параметров (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, маршрутизацию между несколькими моделями, поддержку зрения и многое другое.

🌟 Если этот проект помог вам, пожалуйста, поставьте звезду!