mlx-serve-mcp

원격 mlx-serve 인스턴스를 호출 가능한 도구로 바꿔주는 MCP 서버 — 따라서 모든 기기의 모든 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 플래그는 환경 변수보다 우선합니다:

기본 모델

각 미디어 도구는 선택적 model 인수를 받습니다. 생략하면 도구는 구성 가능한 기본값(환경 변수 → 내장)으로 대체됩니다:

모델 권장 사항 (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도 유사한 로드 실패 문제가 있습니다.

결론: generate_image와 edit_image 모두 Runpod/FLUX.2-klein-4B-mflux-4bit를 사용하세요. 이 그룹에서 안정적으로 로드되면서 (얼굴을 포함해) 좋은 결과를 내는 유일한 이미지 모델입니다.

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": "..."}를 추가하세요.

도구

출력 파일은 타임스탬프가 포함된 이름으로 <output-dir>/{images,audio,video,mesh}/ 아래에 저장됩니다. 모든 도구는 결과 텍스트에 절대 경로를 보고합니다.

프롬프트

prompts/list / prompts/get를 통해 노출되는 원클릭 프롬프트 템플릿:

리소스

resources/list / resources/read를 통해 노출되는 실시간 데이터 소스:

LobeHub 마켓플레이스

이 패키지는 전체 lhm.plugin.json 매니페스트와 에이전트 검색을 위한 skill.md를 포함하여 LobeHub MCP Marketplace에 게시되어 있습니다.

설계 노트

• 비디오: 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