LocalAiMCP

LocalAI를 위한 무상태(stateless) 비동기 FastMCP 제어 평면입니다. 번들된 LocalAI Swagger에는 114개 경로 / 123개 작업이 포함되어 있으며, 123개 모두 타입이 지정되고 검증된 호출 가능 객체를 통해 사용할 수 있습니다. 모든 MCP 요청마다 약 123개의 작업 스키마를 모델에 보내지 않도록 선별된 집합만 직접 광고되며, 나머지는 요청 시 발견하고 실행할 수 있습니다.

두 개의 Swagger WebSocket 작업은 제한된 단일 호출 교환으로 구현되며, multipart 경로는 파일 업로드를 지원하고, 이진 응답은 ./data/output 아래에 저장하거나 충분히 작을 때 base64로 인라인 반환할 수 있습니다.

실행

git clone https://github.com/twinlunarstarz-dev/LocalAiMCP.git
cd LocalAiMCP
cp .env.example .env
# Edit LOCALAI_BASE_URL / LOCALAI_API_KEY if needed.
docker compose up -d --build

MCP 엔드포인트는 다음과 같습니다:

http://localhost:8000/mcp

VS Code/Zoo Code 또는 다른 Streamable HTTP MCP 클라이언트의 경우 해당 URL을 원격 MCP 서버 엔드포인트로 사용하세요. 컨테이너는 LocalAI에 대해 기본적으로 host.docker.internal:8080을 사용하며 Linux host-gateway 매핑을 포함합니다.

Related MCP server: mcp-file-system-lmstudio

선별된 도구 표면

서버는 기본적으로 123개의 LocalAI 작업을 모두 광고하지 않습니다. 기본 프리셋은 일반적으로 유용한 20개의 작업 도구와 5개의 고정 검색/시스템 헬퍼를 광고합니다.

기본적으로 직접 노출되는 작업 도구:

# System/model information
get_system_info
get_metrics
get_token_metrics
list_models
list_model_capabilities
get_backend_monitor

# Generation/media
chat
complete_text
generate_image
inpaint_image
generate_sound
generate_video
text_to_speech
text_to_speech_with_voice

# Voice
list_voice_profiles
create_voice_profile
analyze_voice
verify_speakers

# 3D
generate_3d_asset
remesh_3d_asset

5개의 고정 MCP 헬퍼는 다음과 같습니다:

list_additional_tools
search_additional_tools
execute_additional_tool
server_health
schema_audit

따라서 기본 tools/list 표면은 약 128개가 아닌 25개 도구입니다. 정확한 개수는 구성 가능합니다.

직접 표시할 LocalAI 작업 구성

LOCALAI_MCP_EXPOSED_TOOLS를 쉼표로 구분된 의미론적 작업 이름 목록으로 설정하세요:

LOCALAI_MCP_EXPOSED_TOOLS=chat,list_models,generate_image,text_to_speech,generate_3d_asset

특수 값:

*       expose all 123 Swagger operations directly
none    expose no Swagger operations directly; use only the gateway/system helpers
gateway-only  same as none

빈 값 또는 설정되지 않은 값은 내장된 20개 작업 프리셋을 사용합니다. 잘못된 이름은 조용히 사라지지 않고 시작 시 실패합니다.

직접 노출을 변경하면 MCP 클라이언트가 tools/list에서 받는 내용에만 영향을 미칩니다. LocalAiMCP에서 숨겨진 작업이 제거되지는 않습니다.

추가 도구 게이트웨이

덜 일반적인 도구는 내부 타입 지정 레지스트리에 유지되며 세 개의 작은 도구를 통해 액세스됩니다.

list_additional_tools

숨겨진 도구 이름의 전체 정렬 목록을 반환하며 스키마가 무거운 내용은 포함하지 않습니다. 모델이 모든 요청에서 해당 스키마를 영구적으로 유지하지 않고도 요청 시 전체 숨겨진 카탈로그를 검사할 수 있도록 의도적으로 간결하게 설계되었습니다.

search_additional_tools

일반 언어 목표 또는 정확한 도구 이름을 사용하여 숨겨진 도구만 검색합니다. 각 일치 항목은 다음을 반환합니다:

• 의미론적 도구 이름

• 상세한 목적/입력/출력 설명

• 태그

• 전체 입력 JSON 스키마

예:

search_additional_tools(query="detokenize token ids")
search_additional_tools(query="transcribe audio")
search_additional_tools(query="install a backend")
search_additional_tools(query="inspect request traces")

execute_additional_tool

의미론적 이름으로 숨겨진 기능을 실행합니다:

{
  "tool_name": "detokenize",
  "arguments": {
    "request": {
      "model": "my-model",
      "tokens": [1, 42, 9001]
    }
  }
}

arguments 객체는 직접 노출된 작업에서 사용하는 동일한 생성된 Pydantic 스키마에 대해 검증됩니다. 잘못되었거나 알 수 없는 필드는 LocalAI 요청이 이루어지기 전에 검증 오류와 예상 입력 스키마를 반환합니다. 이것은 curl 스타일 디스패처가 아닙니다. 모델은 HTTP 메서드/경로 대신 의미론적 도구 이름과 타입이 지정된 인수를 사용합니다.

직접 노출된 작업은 execute_additional_tool에 의해 의도적으로 거부됩니다. 클라이언트는 일반 MCP 도구를 직접 호출해야 합니다.

이전의 고급 raw_request 탈출구와 probe_safe_endpoints 헬퍼는 숨겨진 추가 도구로 유지되므로 tools/list를 줄여도 해당 기능이 제거되지 않습니다.

LLM 지향 설명

레지스트리는 모델이 사전 LocalAI API 지식 없이도 사용할 수 있도록 설계되었습니다:

• 도구 이름은 HTTP 경로나 메서드를 그대로 반영하지 않고 작업을 설명합니다.

• 모든 타입 지정 HTTP 작업은 목적, 예상 입력 및 성공 출력을 명시합니다.

• JSON 요청 스키마는 필드 수준 설명을 포함하며, Swagger가 Request와 같은 내용만 말하거나 필드를 문서화하지 않은 경우 보수적인 대체 지침도 포함합니다.

• 참조된 요청 객체는 유용한 최상위 필드를 설명에 직접 표시합니다.

• 응답 설명은 데이터가 data, text, events, base64 또는 saved_path 아래에 나타나는지 설명합니다.

• 검색은 숨겨진 도구가 관련된 경우에만 전체 입력 스키마를 반환합니다.

• 사용자 정의 헤더 및 호출별 타임아웃과 같은 래퍼 배관은 일반 타입 지정 작업에서 제외됩니다.

예를 들어, 숨겨진 도구 detokenize는 해당 요청에 다음이 포함된다고 설명합니다:

• tokens: 텍스트로 다시 변환할 정수 토큰 ID

• model: 사용할 토크나이저의 LocalAI 모델 이름 또는 별칭

그리고 JSON 응답에는 역토큰화된 텍스트인 content가 포함된다고 설명합니다.

설계

• FastMCP 3.4.7, 재현성을 위해 고정됨.

• Streamable HTTP + 무상태 모드. 검색과 실행이 대화형/세션 상태 대신 프로세스 로컬 불변 레지스트리를 사용하므로 여러 Uvicorn 워커가 안전합니다.

• httpx를 사용한 비동기 LocalAI I/O; 독립적인 호출은 동시에 실행될 수 있습니다.

• 의미론적 이름과 생성된 입력 검증을 갖춘 123개의 타입 지정 Swagger 작업 호출 가능 객체; 구성된 하위 집합만 FastMCP에 직접 등록됩니다.

• 숨겨진 작업을 위한 온디맨드 게이트웨이로, 모든 요청에서 모든 스키마를 광고하지 않고도 전체 LocalAI 기능을 유지합니다.

• 오디오, 이미지, GLB 파일, 브랜딩 자산 및 음성 프로필을 위한 Multipart 지원. 파일 인수는 data: URI, base64:<data>, HTTP(S) URL 또는 /data 아래의 파일을 허용합니다.

• 오디오/이미지/GLB 응답을 위한 이진 지원. 작은 페이로드는 base64로 반환되며, 이진 페이로드는 /data/output에 저장할 수도 있습니다.

• SSE 인식 응답 처리는 LocalAI SSE 이벤트를 구조화된 결과로 집계합니다.

• 제한된 교환을 사용하는 백엔드 로그 스트리밍 및 실시간 오디오 변환을 위한 WebSocket 지원.

• LOCALAI_API_KEY를 통한 Bearer 인증; 토큰은 코드에 저장되지 않으며 MCP 클라이언트에 반환되지 않습니다.

응답 래퍼

타입 지정 HTTP 작업은 예측 가능한 래퍼를 반환합니다:

• ok: LocalAI가 성공적인 HTTP 상태를 반환했는지 여부

• status_code: LocalAI HTTP 상태

• elapsed_ms: 요청 지속 시간

• data: 파싱된 JSON 응답 본문

• text: 텍스트 응답

• events: 수집된 SSE data: 페이로드

• base64, size_bytes, mime_type, saved_path: 해당하는 경우 이진 응답 메타데이터/콘텐츠

응답 본문을 사용하기 전에 항상 ok를 확인하세요.

파일 입력

multipart 도구의 경우 파일 인수는 다음 중 하나일 수 있습니다:

• data:<mime>;base64,<payload>

• base64:<payload>

• MCP 컨테이너가 가져올 수 있는 http:// 또는 https:// URL

• LOCALAI_MCP_FILE_ROOT 아래의 로컬 경로(Compose에서 /data)

Compose 파일은 ./data를 /data에 마운트합니다.

LocalAI 스트리밍 동작

stream=true를 설정하는 LocalAI 요청 본문은 변경 없이 전달됩니다. LocalAI가 text/event-stream으로 응답하면 MCP 호출은 SSE data: 이벤트를 수집하고 LocalAI 스트림이 종료될 때 반환합니다.

두 개의 Swagger WebSocket 경로는 특별히 매핑됩니다:

• stream_backend_logs: 모델에 대한 백엔드 로그 메시지를 max_messages까지 수집한 후 닫습니다.

• stream_audio_transform: 하나의 세션/구성 객체와 base64 PCM 프레임을 보내고 변환된 메시지를 max_messages까지 수집한 후 닫습니다.

LOCALAI_MCP_EXPOSED_TOOLS에 따라 직접 또는 숨김일 수 있습니다. 숨겨진 WebSocket 도구는 execute_additional_tool을 통해 계속 실행할 수 있습니다.

검증

저장소 테스트는 다음을 검증합니다:

• 정확한 Swagger 적용 범위: 114개 경로 / 123개 작업

• 123개의 고유한 검토된 의미론적 이름

• 기본 선별 노출 개수 및 MCP tools/list 개수

• 전체 숨겨진 이름 카탈로그

• 숨겨진 검색이 실제 설명과 생성된 입력 스키마를 반환하는지

• 숨겨진 실행이 네트워크 액세스 전에 인수를 검증하는지

• 모든 비-WebSocket 작업 설명이 입력과 출력을 설명하는지

• 참조된 요청/응답 스키마가 실제 필드를 표시하는지

• detokenize가 요청 시 유용한 토큰/모델/콘텐츠 지침을 노출하는지

• WebSocket 감지, 응답 래핑 및 이진 처리

• 빌드된 휠에 번들된 4개의 Swagger 페이로드 부분이 모두 포함되는지

의존성이 설치된 상태로 로컬에서 실행:

python -m pip install -e '.[test]'
pytest

컨테이너 검증:

docker compose config
docker compose build

MCP 클라이언트는 http://localhost:8000/mcp에 대해 일반 MCP initialize 핸드셰이크를 수행해야 합니다.

구성

보안 참고 사항

추가 도구 게이트웨이는 모델/백엔드 설치/삭제, 작업/잡 제어, 추적/로그 정리, 브랜딩, 노드 예산 및 음성 프로필 관리를 포함한 LocalAI 관리/파괴적 작업을 여전히 실행할 수 있습니다. tools/list에서 도구를 숨기는 것은 컨텍스트 크기를 줄일 뿐이며 인증 경계가 아닙니다. 인증 및 네트워크 액세스 제어 없이 포트 8000을 신뢰할 수 없는 네트워크에 공개하지 마세요.