LocalAiMCP

用于 LocalAI 的无状态、异步 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 服务器端点。容器默认使用 host.docker.internal:8080 作为 LocalAI 地址，并包含 Linux host-gateway 映射。

Related MCP server: mcp-file-system-lmstudio

精选工具面

服务器默认不会公布全部 123 个 LocalAI 操作。默认预设公布 20 个常用操作工具，外加五个固定的发现/系统辅助工具。

默认直接暴露的操作工具：

# 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

五个固定的 MCP 辅助工具为：

list_additional_tools
search_additional_tools
execute_additional_tool
server_health
schema_audit

因此，默认的 tools/list 工具面为 25 个工具，而非约 128 个。确切数量可配置。

配置哪些 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：要转换回文本的整数 token ID

• model：应使用其分词器的 LocalAI 模型名称或别名

并且 JSON 响应包含 content，即反分词后的文本。

设计

• FastMCP 3.4.7，固定版本以确保可重现性。

• Streamable HTTP + 无状态模式。多个 Uvicorn worker 是安全的，因为发现和执行使用进程本地的不可变注册表，而非对话/会话状态。

• 使用 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 按需提供有用的 token/模型/内容指导

• WebSocket 检测、响应包装和二进制处理

• 构建的 wheel 包含所有四个随附的 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 端口发布到不受信任的网络。