Local-MMCP

本地多模态 MCP Server — 为 Claude Code / Codex / Cline 等 AI 客户端提供视觉、文档、音频、视频、GUI 自动化能力

项目简介

Local-MMCP 是一个基于 MCP (Model Context Protocol) 的本地多模态服务器，通过 stdio transport 向 AI 客户端暴露 9 个多模态工具。

核心设计理念：本地优先、隐私安全、优雅降级。所有数据处理在本地完成，无需将图片/文档/音频上传到第三方服务。

架构总览

MCP Client (Claude Code / Codex / Cline / Roo / OpenCode 等)
        │
        ▼
Local-MMCP MCP Server (stdio transport)
        │
        ├── oMLX 视觉/文本模型 (本地 Apple Silicon)
        │   ├── gemma-4-31B-it-Uncensored-MAX-MLX (视觉)
        │   └── Huihui-Qwen3.6-35B-A3B-Claude-4.7-Opus-abliterated-mlx-8bit (文本)
        │
        ├── MinerU / PaddleOCR (文档解析)
        ├── Qwen3-ASR / mlx-audio (语音转写)
        ├── ffmpeg (视频处理)
        └── Playwright / ADB / macOS Accessibility (GUI 自动化)

分层架构

Server (MCP Protocol Handler)
    └── Tools (9 个工具模块)
        ├── Clients (oMLX API 客户端 + 模型生命周期管理)
        ├── Adapters (外部工具适配器)
        └── Utils (图片处理 / 安全 / JSON 工具)

工具清单

工具	用途	依赖	需确认
health_check	检查所有组件可用性（支持 deep 模式验证 VLM）	无	❌
vision_inspect	分析图片：截图理解、UI 分析、图表、错误诊断	oMLX VLM	❌
vision_crop_verify	裁剪图片局部放大复核	oMLX VLM	❌
vision_diff	比较两张图片差异（像素 + 语义）	oMLX VLM	❌
doc_parse	文档转 Markdown/JSON（PDF/DOCX/PPTX/XLSX/图片）	MinerU 或 PaddleOCR	❌
audio_transcribe	音频转写（WAV/MP3/M4A/FLAC）	mlx-audio (Qwen3-ASR)	❌
video_index	视频时间线索引（抽帧 + ASR + VLM 理解）	ffmpeg + oMLX + mlx-audio	❌
gui_observe	观察 GUI 状态（浏览器/Android/macOS）	Playwright / ADB / AppKit	❌
gui_act	执行 GUI 动作（点击/输入/滑动等）	Playwright / ADB / AppKit	✅

快速开始

1. 环境要求

• 硬件: Mac with Apple Silicon (M1+), 推荐 128GB+ 统一内存
• 系统: macOS 14+
• Python: 3.11+
• oMLX: omlx.ai 本地模型推理服务
• 包管理: uv

2. 安装

git clone https://github.com/rorojiao/local-mmcp.git
cd local-mmcp
uv sync

# 可选依赖（按需安装）
uv pip install mlx-audio          # 语音转写
uv pip install pyautogui           # macOS 桌面自动化

3. 配置

cp config.example.yaml config.yaml
# 编辑 config.yaml，调整 omlx 端口、模型名、安全路径等

⚠️ config.yaml 含本地路径和 API 密钥，已在 .gitignore 中排除，不会被提交。

4. 配置 MCP Client

Claude Code

在 ~/.claude/settings.json 中添加：

{
  "mcpServers": {
    "local-mmcp": {
      "command": "uv",
      "args": [
        "run",
        "--project",
        "/ABSOLUTE/PATH/local-mmcp",
        "python",
        "-m",
        "local_mmcp.server"
      ],
      "env": {
        "MMCP_CONFIG": "/ABSOLUTE/PATH/local-mmcp/config.yaml"
      }
    }
  }
}

其他 MCP Client

修改对应配置文件，使用相同 command/args/env 结构即可。

5. 运行检查

# 直接运行 MCP Server（测试用）
MMCP_CONFIG=config.yaml uv run python -m local_mmcp.server

# 运行诊断脚本
bash scripts/doctor.sh

安全设计

路径白名单

只允许访问 config.yaml 中 security.allowed_roots 列出的目录：

security:
  allowed_roots:
    - "~/Projects"
    - "~/Desktop"
    - "~/Downloads"
    - "~/working"
    - "~/Pictures"
    - "/tmp"
    - "~/.claude"

路径黑名单

自动拒绝包含以下模式的路径：.ssh、.gnupg、Library/Keychains、.env、id_rsa、id_ed25519

确认令牌机制

高风险 GUI 操作（gui_act、adb_install 等）需要一次性确认令牌，TTL 300 秒。

macOS 文件图标检测

当用户从 Finder 复制文件并粘贴到 AI 客户端时，系统可能传递文件图标而非真实图片内容。Local-MMCP 会：

1. 检测：通过灰度 + alpha 多样性 + 尺寸综合评分识别文件图标
2. 自动替换：三层策略找到原始文件（剪贴板路径 → 剪贴板图片数据 → 文件系统搜索）
3. 不阻塞：检测失败时仅警告，不阻断分析流程

设计说明

详细的架构文档和设计说明请参考：

文档	内容
ARCHITECTURE.md	完整架构文档：数据流、模块详解、性能数据
local-mmcp-dev-doc.md	原始设计文档：功能定义、接口设计、实现计划
CHANGELOG.md	版本变更记录

核心设计模式

1. 单一 image_source 参数：对齐 ZhiPu MCP 设计，自动识别 URL / base64 / 本地路径
2. 模型生命周期管理：ModelManager 单模型互斥 + 空闲超时自动卸载（300 秒）
3. 优雅降级：VLM 不可用时降级为 OCR 模式，不会因单一组件崩溃
4. 最小图像处理：不做 normalize/resize，直接传原始文件给 VLM API

测试

# 运行所有单元测试（57 个测试用例）
uv run pytest tests/ -v

# 运行特定测试
uv run pytest tests/test_all.py -v         # 全量集成测试
uv run pytest tests/test_model_manager.py  # 模型管理器测试

测试覆盖

测试类别	用例数	覆盖内容
health_check	9	所有组件状态检查
vision_inspect	3	本地路径/URL/base64
安全路径校验	12	合法路径/非法路径/deny 列表
确认令牌	6	创建/验证/重用/过期
文件图标检测	5	真实照片/海报/模拟图标
OmlxClient	10	初始化/JSON/data URL
vision_crop_verify	1	裁剪数学验证
vision_diff	1	像素+语义差异
错误路径	12	空参数/非法路径/不存在

已知限制

1. Apple Silicon only — 依赖 omlx + MLX 框架，不支持 Intel Mac 或 Linux
2. 内存需求高 — 视觉模型 (gemma-4-31B) 约 58GB，推荐 128GB+ 统一内存
3. 模型加载延迟 — 冷启动加载模型约 20 秒，后续请求复用已加载模型
4. MinerU/PaddleOCR — 需单独安装，未安装时 doc_parse 返回安装建议
5. macOS 权限 — GUI 自动化需要辅助功能权限（System Preferences → Privacy → Accessibility）
6. 剪贴板时效性 — macOS 文件图标替换依赖剪贴板内容，复制后需立即使用

项目结构

local-mmcp/
├── local_mmcp/
│   ├── server.py           # MCP 服务器入口
│   ├── config.py           # Pydantic 配置模型
│   ├── security.py         # 路径安全校验
│   ├── schemas.py          # 数据模型
│   ├── errors.py           # 错误处理
│   ├── tools/              # 9 个工具实现
│   │   ├── vision.py       # vision_inspect / crop_verify / diff
│   │   ├── document.py     # doc_parse
│   │   ├── audio.py        # audio_transcribe
│   │   ├── video.py        # video_index
│   │   ├── gui.py          # gui_observe / gui_act
│   │   └── health.py       # health_check
│   ├── clients/
│   │   └── omlx_client.py  # oMLX API 客户端 + ModelManager
│   ├── adapters/           # 外部工具适配器
│   │   ├── paddleocr_adapter.py
│   │   ├── mineru_adapter.py
│   │   ├── qwen_asr_adapter.py
│   │   ├── ffmpeg_adapter.py
│   │   ├── playwright_adapter.py
│   │   ├── adb_adapter.py
│   │   ├── macos_adapter.py
│   │   └── ui_tars_adapter.py
│   ├── utils/
│   │   ├── images.py       # 图片处理 + 图标检测/替换
│   │   ├── files.py        # 文件工具
│   │   ├── json_tools.py   # JSON 提取
│   │   └── subprocesses.py # 子进程管理
│   └── prompts/            # 工具 prompt 模板
├── tests/                  # 57 个测试用例
├── scripts/
│   ├── doctor.sh           # 诊断脚本
│   └── run_mcp.sh          # 运行脚本
├── config.example.yaml     # 配置模板
├── ARCHITECTURE.md         # 架构文档
├── local-mmcp-dev-doc.md   # 原始设计文档
└── pyproject.toml          # 项目配置

License

MIT