OmniParser MCP Server

　English

把微软 OmniParser（纯视觉 GUI Agent 的屏幕解析工具）封装为 Model Context Protocol 服务，让 Claude Desktop、Cursor、Cline 等 任何 MCP 客户端都能调用屏幕解析能力：给定一张截图，返回结构化的 UI 元素（文本、图标、坐标、语义描述）。

本仓库是独立项目：不包含 OmniParser 模型与官方代码，只提供一个薄 MCP 代理层，通过 HTTP 调用 官方 omniparserserver 服务。

架构

MCP 客户端 (Claude Desktop / Cursor / Cline / ...)
   │  stdio
   ▼
omniparser_mcp.py   (本仓库, MCP Server, 薄代理, 仅依赖 mcp + httpx)
   │  HTTP localhost (OMNIPARSER_API_URL, 默认 http://127.0.0.1:8010)
   ▼
omniparserserver    (官方 OmniParser, FastAPI, 模型常驻)
                     YOLOv9 图标检测 + Florence-2 图标描述 + EasyOCR 文本识别

MCP 层不感知 OmniParser 的安装位置——它只和 HTTP 地址通信。OmniParser 可以装在本机任意目录、 另一台机器、Docker 或远程服务器，只需把地址告诉 MCP（OMNIPARSER_API_URL）。

端口说明：本项目默认后端端口是 8010（不是官方默认的 8000），避免与常用的 8000 端口 开发工具冲突。端口可任意更换：启动后端时指定 -Port，并把 OMNIPARSER_API_URL 改成对应地址 即可（二者保持一致）。

Related MCP server: screen-mcp

环境变量

三种方式指定 OMNIPARSER_API_URL：环境变量 / MCP 客户端配置的 env 字段 / 代码默认值（兜底）。

快速开始

最快路径：一条命令（推荐）

git clone https://github.com/cute-aaa/OmniParser-MCP
cd OmniParser-MCP
python setup_backend.py --omni-home D:\OmniParser

setup_backend.py 会自动完成（各步可用 flag 跳过）：

结束后脚本会打印可直接粘贴的 MCP 客户端配置。

国内网络：加 --hf-endpoint https://hf-mirror.com。 已有装好的环境/权重，只想启动：python setup_backend.py --omni-home D:\OmniParser --start-only。 无 GPU：加 --device cpu（脚本默认自动探测）。

完成后用 python test_mcp.py 验证：应看到 3 个工具、后端 ✅ 就绪、parse_screen 返回元素列表。

Linux / WSL2

同一条命令即可，解释器是 .venv-omni/bin/python：

git clone https://github.com/cute-aaa/OmniParser-MCP
cd OmniParser-MCP
python3 setup_backend.py --omni-home ~/OmniParser
# 国内网络：再加 --hf-endpoint https://hf-mirror.com

用 CUDA 时必须先装 C 工具链（Debian/Ubuntu/WSL2）：

sudo apt install build-essential python3.12-dev

原因：torch 的 attention kernel 走 triton，triton 在首次 parse 时用系统 gcc + Python.h 现场编译 driver.c。缺了它们后端能正常启动、/probe/ 也绿，但每次 /parse/ 都返回 500（subprocess.CalledProcessError ... triton/runtime/build.py）， 是个很晚才暴露、也很难猜的失败。setup_backend.py 会在启动前预检并打印这两个包名。 只想用 CPU 就无需工具链，加 --device cpu 即可跳过 triton。

已验证：WSL2 + Ubuntu 24.04 + RTX 4070 Ti，完全离线（HF_HUB_OFFLINE=1）冷启动， test_mcp.py 1080p 截图返回 134 元素、耗时 3.9 秒。

手动路径（想自己掌控每一步时）

1. 安装官方 OmniParser（一次性）

git clone https://github.com/microsoft/OmniParser
cd OmniParser
conda create -n omni python==3.12 && conda activate omni
pip install -r requirements.txt
# 国内网络先设置 $env:HF_ENDPOINT="https://hf-mirror.com"，再按官方 README 下载权重。
# 需要的权重（约 1.3 GB）：
#   weights/icon_detect_v3/model.pt                     （YOLOv9-E 图标检测器）
#   weights/icon_caption_florence/{config.json, generation_config.json, model.safetensors} （Florence-2 描述模型）

权重下载完成后，可先手动验证后端能起来（注意端口：本项目统一用 8010， 与官方默认 8000 不同，请显式加 --port 8010）：

python -m omniparserserver --caption_model_name florence2 `
    --caption_model_path ../../weights/icon_caption_florence `
    --device cuda --BOX_TRESHOLD 0.05 --host 127.0.0.1 --port 8010

2. 启动后端（二选一）

方式 A — 手动启动（推荐，后端生命周期自己掌控）

# 从本仓库运行。start_backend.ps1 会自动向上层目录探测 OmniParser，
# 但本仓库 clone 后不含官方 OmniParser，通常需显式指定 -OmniParserHome：
pwsh -File start_backend.ps1 -OmniParserHome D:\OmniParser -Device cuda `
    -Python D:\path\to\omni-env\python.exe   # 可选：后端专用解释器

方式 B — MCP 自动启动

在 MCP 客户端配置的 env 里加上 OMNIPARSER_HOME（见下节），后端未运行时会自动拉起并等待就绪 （首次加载模型约 30–60 秒，最长等待 240 秒），无需手动操作。

3. 安装本仓库依赖并注册 MCP

pip install -r requirements.txt   # 仅 mcp(<2.0) + httpx

⚠️ transformers 版本要求：OmniParser 的 Florence-2 依赖 2024 年的 remote code，与 transformers 5.x 不兼容（会报 TokenizersBackend has no attribute additional_special_tokens / forced_bos_token_id 等错误）。请在 OmniParser 环境中固定 pip install "transformers==4.46.3"（或任何 4.x）。 如果跑 MCP 的 Python 环境不是这个环境，用 -Python / OMNIPARSER_PYTHON 指向后端专用解释器即可。

本仓库依赖建议装进与步骤 1 相同的 conda 环境（omni），MCP 层与 OmniParser 层共用 一个 Python 环境即可。

Claude Desktop — 编辑 %APPDATA%\Claude\claude_desktop_config.json（把 D:\OmniParser-MCP、D:\OmniParser 替换为你的实际路径）：

{
  "mcpServers": {
    "omniparser": {
      "command": "python",
      "args": ["D:\\OmniParser-MCP\\omniparser_mcp.py"],
      "env": {
        "OMNIPARSER_API_URL": "http://127.0.0.1:8010",
        "OMNIPARSER_HOME": "D:\\OmniParser",
        "OMNIPARSER_DEVICE": "cuda"
      }
    }
  }
}

Cursor / Cline — 本仓库已附带现成配置（使用 ${workspaceFolder} 变量，clone 即用）， 按需在 env 里补 OMNIPARSER_HOME 即可开启自动启动：

• .cursor/mcp.json

• .cline/mcp_settings.json

4. 自测

python test_mcp.py        # 完整测试：需后端已在 8010 运行、且仓库内放一张截图
                          # （默认用 test_image.png，可替换为任意截图）
python test_ci_smoke.py   # 轻量冒烟测试：无需后端/GPU，任何环境可跑

test_mcp.py 会枚举工具、检查后端状态并解析截图（解析结果打印时截断为前 1500 字符）； test_ci_smoke.py 只验证 MCP server 能启动、工具可用、无后端时优雅报错。

工具说明

调用示例：

用户: 解析这个截图 C:\shots\app.png 并告诉我搜索框在哪
Agent: 调用 parse_screen(image_path="C:\shots\app.png", image_size="2560,1440")
       → [12] text px=(320,180,880,230) content='Search...' interactivity=True
       搜索框中心 ≈ (600, 205)

常见问题

License

MIT。OmniParser 模型权重遵循其各自的 License。