LMStudio-MCP

Claude가 LM Studio를 통해 로컬에서 실행 중인 LLM 모델과 통신할 수 있도록 하는 모델 제어 프로토콜(MCP) 서버입니다.

개요

LMStudio-MCP는 Claude(MCP 기능 포함)와 로컬에서 실행 중인 LM Studio 인스턴스 간의 브리지를 생성합니다. 이를 통해 Claude는 다음 작업을 수행할 수 있습니다:

• LM Studio API의 상태 확인

• 사용 가능한 모델 목록 확인

• 현재 로드된 모델 가져오기

• 로컬 모델을 사용하여 채팅 및 원시 텍스트 완성 생성

• 의미론적 검색 및 RAG를 위한 벡터 임베딩 생성

• 응답 ID를 통한 상태 유지 다중 턴 대화

• 고정된 시스템 프롬프트로 지속적인 대화 시작 및 계속

이를 통해 Claude의 기능과 개인 모델을 결합하여 Claude 인터페이스를 통해 로컬에서 실행 중인 모델을 활용할 수 있습니다.

Related MCP server: Ollama MCP Server

사전 요구 사항

• Python 3.7+

• LM Studio가 로컬에 설치되어 있고 모델이 로드되어 있어야 함

• MCP 액세스 권한이 있는 Claude

• 필요한 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를 참조하세요.

선택 사항: 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 브리지를 통해 전송되는 모든 완성 요청에 적용됩니다.

시스템 프롬프트 예시

일반 어시스턴트 — 깔끔하고 직접적임:

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가지 도구를 제공합니다:

다중 턴 대화 워크플로우

로컬 모델과 지속적인 대화를 실행하는 권장 방법:

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)은 호환성 문제가 있을 수 있습니다.

• 이 브리지는 현재 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 연결 문제

Claude가 LM Studio에 연결하려고 할 때 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 by @ahmedibrahim085 — 이 프로젝트를 기반으로 구축된 강력한 확장 기능으로, 자율 에이전트 루프, 37개의 도구, 동적 MCP 검색, 다중 모델 라우팅, 비전 지원 등을 추가합니다.

🌟 이 프로젝트가 도움이 되었다면 별표를 눌러주세요!