Skip to main content
Glama
deenesjakoruzh
Congenital

mlx-serve-mcp

by Congenital
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

MCP Badge

mlx-serve-mcp

一个 MCP 服务器，可将远程 mlx-serve 实例变成可调用的工具 —— 这样任何设备上的任何 MCP 客户端（Claude Code、Claude Desktop、Cline 等）都可以通过你 Mac 的 ip:port 生成图像、语音、音乐、视频和 3D 网格。

mlx-serve 在 Apple Silicon 上原生运行模型；这个桥接器一侧使用 MCP 协议，另一侧对接 mlx-serve 的 OpenAI 风格媒体 API（/v1/images、/v1/audio、/v1/video、/v1/3d）。本地不会生成任何内容——你的机器只通过 HTTP 与服务器通信。

┌──────────────┐  stdio/MCP   ┌────────────────┐    HTTP     ┌──────────────────┐
│ MCP client   │ ◄──────────► │  mlx-serve-mcp │ ──────────► │ mlx-serve server │
│ (any device) │              │  (this package)│  ip:port    │  (Apple Silicon) │
└──────────────┘              └────────────────┘             └──────────────────┘

安装与运行

需要 Python ≥ 3.10。如果已安装 uv：

cd mlx-serve-mcp
uv sync                 # create venv + install deps
uv run mlx-serve-mcp --url 192.168.1.10:11234

URL 接受裸 ip:port（默认使用 http）、host:port 或完整的 http(s)://... URL。

配置

CLI 标志会覆盖环境变量：

标志

环境变量

默认值

含义

--url

MLX_SERVE_URL

http://127.0.0.1:11234

mlx-serve 地址

--api-key

MLX_SERVE_API_KEY

(none)

服务器启用 API 密钥认证时的 Bearer 密钥

--output-dir

MLX_SERVE_OUTPUT_DIR

~/Downloads/mlx-serve-mcp

生成的媒体文件的写入位置

--timeout

MLX_SERVE_TIMEOUT

1800

HTTP 超时时间（秒）（视频/音乐可能需要数分钟）

默认模型

每个媒体工具都接受可选的 model 参数。省略时，工具会回退到可配置的默认值（环境变量 → 内置）：

环境变量

工具

内置默认值

MLX_SERVE_IMAGE_MODEL

generate_image

Runpod/FLUX.2-klein-4B-mflux-4bit

MLX_SERVE_IMAGE_EDIT_MODEL

edit_image

Runpod/FLUX.2-klein-4B-mflux-4bit

MLX_SERVE_TTS_MODEL

text_to_speech

mlx-community/Qwen3-TTS-12Hz-1.7B-Base-bf16

MLX_SERVE_MUSIC_MODEL

generate_music

ddalcu/MiniMax-Music3-MLX-Serve-8bit

MLX_SERVE_VIDEO_MODEL

generate_video

ddalcu/MiniMax-H3-FL2VA-MLX-Serve-8bit

MLX_SERVE_MESH_MODEL

generate_3d

ddalcu/Hunyuan3D-2.1-MLX-Serve-8bit

模型推荐（基于 mlx-serve 上的实际测试）：

  • ddalcu/Mage-Flow-Turbo-MLX-Serve-8bit 速度很快，但质量低于 Runpod/FLUX.2-klein-4B-mflux-4bit —— 尤其是人脸生成往往 会变形。不过，它在渲染图像中的文字方面远比 mlx-community/flux2-klein-9b-4bit 可靠，因此对于以文字为中心的艺术作品（海报、排版、标牌）而非人像， ddalcu/Mage-Flow-Turbo-MLX-Serve-8bit 是推荐选择。

  • ddalcu/Mage-Flow-Edit-Turbo-MLX-Serve-8bit 在 mlx-serve 上可能会遇到权重/参数 错误（Model load failed: MissingMageFlowWeight），导致 该模型无法使用。

  • mlx-community/flux2-klein-9b-4bit 也有类似的加载失败问题。

结论：使用 Runpod/FLUX.2-klein-4B-mflux-4bit 用于 generate_image 和 edit_image —— 它是这一组中唯一 既能可靠加载又能产生良好效果（包括人脸）的图像模型。

在 MCP 客户端配置中设置这些环境变量，以固定服务器上实际安装的模型：

{
  "mcpServers": {
    "mlx-serve": {
      "command": "uv",
      "args": ["--directory", "/path/to/mlx-serve-mcp", "run", "mlx-serve-mcp", "--url", "192.168.1.10:11234"],
      "env": {
        "MLX_SERVE_API_KEY": "private",
        "MLX_SERVE_IMAGE_MODEL": "ddalcu/Mage-Flow-Turbo-MLX-Serve-8bit",
        "MLX_SERVE_TTS_MODEL": "mlx-community/Qwen3-TTS-12Hz-1.7B-Base-bf16"
      }
    }
  }
}

Related MCP server: imagine-mcp

接入你的 MCP 客户端

Claude Code（.mcp.json / claude mcp add）：

{
  "mcpServers": {
    "mlx-serve": {
      "command": "uv",
      "args": [
        "--directory", "/absolute/path/to/mlx-serve-mcp",
        "run", "mlx-serve-mcp",
        "--url", "192.168.1.10:11234"
      ]
    }
  }
}

Claude Desktop（claude_desktop_config.json）使用相同的 command/args 结构。如果服务器需要密钥，请添加 "env": {"MLX_SERVE_API_KEY": "..."}。

工具

工具

端点

返回内容

health_check

GET /health

可达性文本

list_models

GET /v1/models

模型 ID + 能力标志（image/speech/music/video/3d/chat）

load_model(model)

POST /v1/load-model

加载到 GPU 内存（可选地设为默认）

unload_model(model)

POST /v1/unload-model

释放 GPU 内存

generate_image(prompt, size?, seed?, steps?, model?)

POST /v1/images/generations

内联图像 + 已保存的 PNG 路径

edit_image(prompt, image_path, mode=edit|variation, ...)

同上

内联图像 + 已保存的 PNG 路径

text_to_speech(text, voice?/ref_audio_path?, speed?, seed?)

POST /v1/audio/speech

已保存的 WAV 路径

generate_music(prompt_style, lyrics?, duration_seconds?, bpm?, task?, src_audio_path?)

POST /v1/audio/music-generations

已保存的 WAV 路径

generate_video(prompt, num_frames?, width?, height?, turbo?, first_frame_image_path?...)

POST /v1/video/generations

已编码的 MP4 路径

generate_3d(image_path, steps?, octree_resolution?, texture?...)

POST /v1/3d/generations

已保存的 GLB 路径

输出文件会写入 <output-dir>/{images,audio,video,mesh}/ 目录下，文件名带时间戳；每个工具都会在其结果文本中报告绝对路径。

提示词

通过 prompts/list / prompts/get 暴露的一键提示词模板：

提示词

功能

create_poster

以文字为中心的海报/排版（Mage-Flow-Turbo —— 文字渲染效果最佳）

portrait_photo

写实人像（FLUX.2-klein-4B —— 人脸效果最佳）

lofi_track

Lo-fi 嘻哈音乐曲目（MiniMax-Music3）

speak_text

自然语音合成（Qwen3-TTS）

image_to_3d

抠图照片 → 带纹理的 GLB（Hunyuan3D-2.1）

short_video

9 帧预览视频（最快路径）

资源

通过 resources/list / resources/read 暴露的实时数据源：

资源

URI

内容

models

mlx-serve://models

带能力标志的实时模型清单

server_status

mlx-serve://status

健康状态、版本、已加载模型

model_guidance

mlx-serve://guidance

每个工具推荐的模型（经过实际测试）

LobeHub 市场

该包已发布到 LobeHub MCP Marketplace，包含完整的 lhm.plugin.json 清单和用于智能体发现的 skill.md。

设计说明

  • 视频：mlx-serve 返回的是原始 RGB8 帧字节（+ 可选的 PCM s16le 音轨），而不是编码后的文件。此桥接器通过 ffmpeg 将它们封装为 H.264/AAC MP4 —— 优先使用系统 ffmpeg，回退到 imageio-ffmpeg 依赖附带的静态二进制文件，因此无需单独安装。

  • 图像：既以内联形式（MCP 图像内容，即时预览）返回，也保存为 PNG 文件。

  • 错误：mlx-serve 的命名 400 错误消息（例如 'speed' must be in (0, 5]）会原样呈现，以便调用方 LLM 自行修正。

  • LoRA 字段有意不暴露：它们需要服务器磁盘上的 .safetensors 路径，这对远程调用者来说通常没有意义。

  • 长时间生成在这里只是慢速 HTTP 请求；如果你的片段规模较大，请调高 --timeout。

开发

uv sync
uv run pytest          # unit tests (mocked HTTP, no server required)
uv run mlx-serve-mcp --help
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd
A
license - permissive license
A
quality
B
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

View all tools

Related MCP Servers

View all related MCP servers

Related MCP Connectors

  • mcp-minimax

    MCP server for MiniMax H3 multimodal video generation

  • runcomfy-mcp

    Remote MCP server for RunComfy Serverless API (ComfyUI): deployments and async inference.

  • mcp-wan

    MCP server for Wan AI video generation

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Congenital/mlx-serve-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server