LocalAiMCP

Ein zustandsloser, asynchroner FastMCP-Kontrollplan für LocalAI. Das gebündelte LocalAI-Swagger enthält 114 Pfade / 123 Operationen, und alle 123 bleiben über typisierte, validierte Aufrufe nutzbar. Um zu vermeiden, dass bei jeder MCP-Anfrage etwa 123 Operations-Schemas an das Modell gesendet werden, wird nur eine kuratierte Auswahl direkt beworben; alles andere ist bei Bedarf auffindbar und ausführbar.

Zwei Swagger-WebSocket-Operationen sind als begrenzte Ein-Aufruf-Austausche implementiert, Multipart-Routen unterstützen Datei-Uploads, und binäre Antworten können unter ./data/output gespeichert und inline als base64 zurückgegeben werden, wenn sie klein genug sind.

Ausführen

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

Der MCP-Endpunkt ist:

http://localhost:8000/mcp

Für VS Code/Zoo Code oder einen anderen Streamable-HTTP-MCP-Client verwenden Sie diese URL als Remote-MCP-Server-Endpunkt. Der Container verwendet standardmäßig host.docker.internal:8080 für LocalAI und enthält die Linux-host-gateway-Zuordnung.

Related MCP server: mcp-file-system-lmstudio

Kuratierte Tool-Oberfläche

Der Server bewirbt nicht standardmäßig alle 123 LocalAI-Operationen. Das Standard-Preset bewirbt 20 häufig nützliche Operations-Tools plus fünf feste Discovery-/System-Helfer.

Standardmäßig direkt exponierte Operations-Tools:

# 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

Die fünf festen MCP-Helfer sind:

list_additional_tools
search_additional_tools
execute_additional_tool
server_health
schema_audit

Somit umfasst die Standard-tools/list-Oberfläche 25 Tools statt etwa 128. Die genaue Anzahl ist konfigurierbar.

Konfigurieren, welche LocalAI-Operationen direkt sichtbar sind

Setzen Sie LOCALAI_MCP_EXPOSED_TOOLS auf eine kommagetrennte Liste semantischer Operationsnamen:

LOCALAI_MCP_EXPOSED_TOOLS=chat,list_models,generate_image,text_to_speech,generate_3d_asset

Spezielle Werte:

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

Ein leerer oder nicht gesetzter Wert verwendet das eingebaute 20-Operations-Preset. Ungültige Namen führen zu einem Startfehler, anstatt still zu verschwinden.

Die Änderung der direkten Exposition betrifft nur, was MCP-Clients in tools/list erhalten; sie entfernt die versteckte Operation nicht aus LocalAiMCP.

Gateway für zusätzliche Tools

Weniger gebräuchliche Tools bleiben in einem internen typisierten Register und werden über drei kleine Tools angesprochen.

list_additional_tools

Gibt die vollständige sortierte Liste der versteckten Tool-Namen zurück und nichts Schema-lastiges. Sie ist bewusst kompakt, damit ein Modell den gesamten versteckten Katalog bei Bedarf inspizieren kann, ohne diese Schemas dauerhaft in jeder Anfrage mitzuführen.

search_additional_tools

Durchsucht nur versteckte Tools anhand eines Ziels in natürlicher Sprache oder eines exakten Tool-Namens. Jeder Treffer liefert:

• semantischer Tool-Name

• detaillierte Zweck-/Eingabe-/Ausgabebeschreibung

• Tags

• vollständiges Eingabe-JSON-Schema

Beispiele:

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

Führt eine versteckte Fähigkeit anhand des semantischen Namens aus:

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

Das arguments-Objekt wird gegen dasselbe generierte Pydantic-Schema validiert, das auch für ein direkt exponiertes Operation verwendet wird. Ungültige oder unbekannte Felder geben einen Validierungsfehler und das erwartete Eingabeschema zurück, bevor eine LocalAI-Anfrage gestellt wird. Dies ist kein curl-artiger Dispatcher: Das Modell verwendet semantische Tool-Namen und typisierte Argumente statt HTTP-Methoden/-Routen.

Direkt exponierte Operationen werden von execute_additional_tool absichtlich abgelehnt; der Client sollte deren normales MCP-Tool direkt aufrufen.

Der frühere erweiterte raw_request-Notausgang und der Helfer probe_safe_endpoints bleiben als versteckte zusätzliche Tools erhalten, sodass die Reduzierung von tools/list diese Fähigkeiten nicht entfernt.

LLM-orientierte Beschreibungen

Das Register ist so gestaltet, dass ein Modell keine Vorkenntnisse über die LocalAI-API benötigt:

• Tool-Namen beschreiben Aufgaben, statt HTTP-Routen oder -Methoden zu spiegeln.

• Jede typisierte HTTP-Operation gibt ihren Zweck, erwartete Eingaben und Erfolgsausgabe an.

• JSON-Anfrageschemas tragen Feldbeschreibungen, einschließlich konservativer Fallback-Hinweise, wenn Swagger nur Dinge wie Request sagt oder ein Feld undokumentiert lässt.

• Referenzierte Anfrageobjekte zeigen nützliche Top-Level-Felder direkt in den Beschreibungen.

• Antwortbeschreibungen erklären, ob Daten unter data, text, events, base64 oder saved_path erscheinen.

• Die Suche gibt das vollständige Eingabeschema nur dann zurück, wenn das versteckte Tool relevant ist.

• Wrapper-Infrastruktur wie benutzerdefinierte Header und Zeitüberschreitungen pro Aufruf bleibt bei normalen typisierten Operationen außen vor.

Beispielsweise erklärt das versteckte Tool detokenize, dass seine Anfrage Folgendes enthält:

• tokens: ganzzahlige Token-IDs, die in Text zurückkonvertiert werden sollen

• model: LocalAI-Modellname oder -Alias, dessen Tokenizer verwendet werden soll

und dass die JSON-Antwort content, den detokenisierten Text, enthält.

Design

• FastMCP 3.4.7, für Reproduzierbarkeit festgepinnt.

• Streamable HTTP + zustandsloser Modus. Mehrere Uvicorn-Worker sind sicher, da Discovery und Ausführung ein prozesslokales unveränderliches Register verwenden, statt Konversations-/Sitzungszustand.

• Asynchrone LocalAI-I/O mit httpx; unabhängige Aufrufe können parallel laufen.

• 123 typisierte Swagger-Operations-Callables mit semantischen Namen und generierter Eingabevalidierung; nur die konfigurierte Teilmenge wird direkt bei FastMCP registriert.

• On-Demand-Gateway für versteckte Operationen, das die volle LocalAI-Funktionalität erhält, ohne jedes Schema bei jeder Anfrage zu bewerben.

• Multipart-Unterstützung für Audio, Bilder, GLB-Dateien, Branding-Assets und Sprachprofile. Dateiargumente akzeptieren data:-URIs, base64:<data>, HTTP(S)-URLs oder Dateien unter /data.

• Binärunterstützung für Audio-/Bild-/GLB-Antworten. Kleine Payloads werden als base64 zurückgegeben; binäre Payloads können auch unter /data/output gespeichert werden.

• SSE-bewusste Antwortverarbeitung aggregiert LocalAI-SSE-Ereignisse zu einem strukturierten Ergebnis.

• WebSocket-Unterstützung für Backend-Log-Streaming und Echtzeit-Audio-Transformationen mit begrenzten Austauschen.

• Bearer-Auth über LOCALAI_API_KEY; kein Token wird im Code gespeichert oder an MCP-Clients zurückgegeben.

Antwort-Wrapper

Typisierte HTTP-Operationen geben einen vorhersehbaren Wrapper zurück:

• ok: ob LocalAI einen erfolgreichen HTTP-Status zurückgegeben hat

• status_code: LocalAI-HTTP-Status

• elapsed_ms: Anfragedauer

• data: geparste JSON-Antwortkörper

• text: Textantworten

• events: gesammelte SSE-data:-Payloads

• base64, size_bytes, mime_type, saved_path: Metadaten/Inhalt binärer Antworten, falls zutreffend

Prüfen Sie immer ok, bevor Sie den Antwortkörper konsumieren.

Dateieingaben

Für Multipart-Tools kann ein Dateiargument eines der folgenden sein:

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

• base64:<payload>

• eine http://- oder https://-URL, die der MCP-Container abrufen kann

• ein lokaler Pfad unter LOCALAI_MCP_FILE_ROOT (/data in Compose)

Die Compose-Datei mountet ./data nach /data.

LocalAI-Streaming-Verhalten

LocalAI-Anfragekörper, die stream=true setzen, werden unverändert weitergeleitet. Wenn LocalAI mit text/event-stream antwortet, sammelt der MCP-Aufruf die SSE-data:-Ereignisse und gibt sie zurück, wenn der LocalAI-Stream endet.

Die beiden Swagger-WebSocket-Routen sind speziell zugeordnet:

• stream_backend_logs: sammelt Backend-Logmeldungen für ein Modell bis zu max_messages und schließt dann.

• stream_audio_transform: sendet ein Sitzungs-/Konfigurationsobjekt plus base64-PCM-Frames, sammelt transformierte Meldungen bis zu max_messages und schließt dann.

Sie können je nach LOCALAI_MCP_EXPOSED_TOOLS direkt oder versteckt sein; versteckte WebSocket-Tools bleiben über execute_additional_tool ausführbar.

Verifizierung

Repository-Tests verifizieren:

• exakte Swagger-Abdeckung: 114 Pfade / 123 Operationen

• 123 eindeutige, überprüfte semantische Namen

• die Standardanzahl der kuratierten Exposition und die MCP-tools/list-Anzahl

• den vollständigen Katalog versteckter Namen

• versteckte Suche, die echte Beschreibungen und generierte Eingabeschemas zurückgibt

• versteckte Ausführung, die Argumente vor Netzwerkzugriff validiert

• jede Nicht-WebSocket-Operationsbeschreibung, die Eingaben und Ausgaben erklärt

• referenzierte Anfrage-/Antwortschemas, die echte Felder zeigen

• detokenize, das nützliche Token-/Modell-/Inhaltshinweise bei Bedarf bereitstellt

• WebSocket-Erkennung, Antwort-Wrapping und Binärverarbeitung

• gebaute Wheels, die alle vier gebündelten Swagger-Payload-Teile enthalten

Lokal mit installierten Abhängigkeiten ausführen:

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

Container-Validierung:

docker compose config
docker compose build

Ein MCP-Client sollte den normalen MCP-initialize-Handshake gegen http://localhost:8000/mcp durchführen.

Konfiguration

Sicherheitshinweis

Das Gateway für zusätzliche Tools kann weiterhin administrative/destruktive LocalAI-Operationen ausführen, einschließlich Modell-/Backend-Installation/-Löschung, Aufgaben-/Job-Steuerung, Trace-/Log-Löschung, Branding, Knotenbudgets und Sprachprofil-Verwaltung. Ein Tool aus tools/list zu verstecken reduziert die Kontextgröße; es ist keine Autorisierungsgrenze. Veröffentlichen Sie Port 8000 nicht in einem nicht vertrauenswürdigen Netzwerk ohne Authentifizierung und Netzwerkzugriffskontrollen davor.