mimo-vision-mcp

MCP를 통해 텍스트 전용 LLM에 비전 기능을 제공하며, Xiaomi MiMo-V2.5 같은 비전 모델을 기반으로 합니다.

**MCP(Model Context Protocol)**를 통해 비전 모델(예: 샤오미 MiMo-V2.5)의 이미지 이해 능력을 멀티모달 기능이 없는 텍스트 LLM에 노출합니다. 텍스트 모델이 이미지/스크린샷/이미지 경로를 만나면 analyze_image, describe_image, extract_text_from_image 등의 도구를 능동적으로 호출하여 비전 기능을 얻을 수 있습니다.

🚀 원클릭 시작(초보자도 1분이면 시작, 명령어 입력 불필요)

이 프로젝트에는 WebUI 원클릭 시작이 내장되어 있으며, 전 과정이 마우스 조작으로 이루어지고 모든 환경 구성을 자동으로 완료합니다. 명령줄 지식이 전혀 필요 없습니다:

1. 이 프로젝트를 다운로드 / 클론하여 로컬에 저장합니다

2. start-webui.bat 더블클릭(Windows) — 스크립트가 자동으로 .env를 생성하고(.env.example에서), 환경/의존성을 자동으로 설치하고, 서비스를 시작한 다음 브라우저를 자동으로 엽니다

3. 브라우저가 열리면 웹 페이지에서 API Key를 입력 → 'CLI에 적용' 클릭하거나, 이미지를 끌어다 놓은 다음 → 비전 모델을 선택하고 → '미리보기 테스트'를 클릭하면 비전 모델이 "그림을 보고 설명"하는 것을 확인할 수 있습니다

최초 시작 시 의존성이 자동으로 설치됩니다(인터넷 연결 필요, 약 1~2분). 이후에는 더블클릭만으로 즉시 실행됩니다. Python을 몰라도 되고, pip를 직접 입력할 필요도 없고, .env를 수동으로 만들 필요도 없습니다 — 스크립트가 전부 자동으로 처리합니다.

명령줄의 텍스트 LLM이 비전 기능을 사용하기 위한 전체 연동 방법은 아래 opencode 연동을 참조하세요.

Related MCP server: mimo-vision-mcp

원리

텍스트 모델은 "스케줄링"을 담당하고, 비전 모델은 "보기"를 담당하며, MCP는 둘을 연결하는 인터페이스입니다 — 이미지 데이터 자체는 텍스트 모델을 거치지 않습니다.

用户给图片路径/URL
  → ① 文本 LLM 根据工具列表 + 调用指引，决定调用 analyze_image
  → ② opencode / 任意 MCP 客户端（stdio）
  → ③ mimo-vision MCP server（图片归一化 + 转发请求）
  → ④ 视觉模型（MiMo-V2.5 等，经 OpenCode Go / 自定义供应商）真正"看"图
  → ⑤ 文本结果原路返回，文本模型转述给用户

기능

• 원클릭 시작: start-webui.bat을 더블클릭하기만 하면 의존성을 자동 설치하고, 서비스를 시작하며, 브라우저를 엽니다. 초보자도 진입 장벽이 없습니다

• 즉시 사용 가능: 기본적으로 OpenCode Go에 연결되며, API Key 하나만 입력하면 시작할 수 있습니다. 샤오미 공식 / 임의의 사용자 지정 공급업체로도 전환할 수 있습니다

• OpenAI 호환 프로토콜 기반, stdio 로컬 전송, opencode / Claude Desktop / Cursor 등 모든 MCP 클라이언트에 연결 가능

• 유연한 이미지 입력: 로컬 경로 / http(s) URL / base64 data URI / 순수 base64 모두 지원

• 다중 이미지 입력 지원, 이미지 형식 자동 인식(JPEG/PNG/GIF/WebP/BMP), 50MB 제한 검증

• 모델에 따라 API 프로토콜 자동 선택: gpt-*/grok-*는 Responses API를 사용하고, 나머지는 chat/completions를 사용합니다(강제 지정 가능)

• WebUI 구성 패널 내장: 시각적으로 모델을 선택하고 미리보기 테스트를 할 수 있으며, 선택 즉시 CLI에 동기화되어 재시작이 필요 없습니다

• API key가 없으면 친절한 오류 메시지를 반환하며, 크래시가 발생하지 않습니다

디렉터리 구조

mimo-vision-mcp/
├── mimo_vision_mcp/
│   ├── config.py           # 配置读取（.env 实时重读）+ 应用到 MCP
│   ├── image_loader.py     # 图片输入归一化 + MIME 探测
│   ├── providers.py        # 供应商注册表 + call_vision（chat/responses 适配）
│   └── server.py           # FastMCP server + 3 个工具
├── webui/                  # WebUI 配置面板（FastAPI + 单页 HTML）
├── tests/                  # 单元测试
├── .github/workflows/ci.yml
├── opencode.example.json   # opencode 接入配置示例
├── AGENTS.md               # 文本模型的调用指引
├── start-webui.bat           # 🚀 一键启动（Windows，双击即用）
├── LICENSE
└── pyproject.toml

설치

python -m venv .venv
# Windows: .\.venv\Scripts\python.exe -m pip install -e ".[dev]"
.venv/bin/python -m pip install -e ".[dev]"

API Key 구성

이 프로젝트는 기본적으로 OpenCode Go 요금제를 통해 MiMo-V2.5를 호출합니다(모델 mimo-v2.5, OpenAI 호환 엔드포인트 https://opencode.ai/zen/go/v1).

1. opencode.ai/auth에서 Go를 구독하고 API Key를 복사합니다

2. .env.example을 .env로 복사하여 작성합니다:

   MIMO_API_KEY=你的-opencode-go-key

환경 변수로도 덮어쓸 수 있습니다(config.py가 호출할 때마다 .env를 실시간으로 다시 읽습니다):

비전 모델 전환: OpenCode Go에서 더 빠른 멀티모달 모델을 사용하려면 MIMO_MODEL을 gpt-5.6-luna(/responses 사용) 또는 minimax-m3로 변경하면 됩니다. 참고: mimo-v2.5-pro는 순수 텍스트 모델이므로 이미지를 볼 수 없습니다.

MCP 서버 실행

# 方式一：控制台脚本
mimo-vision-mcp
# 方式二：模块运行
python -m mimo_vision_mcp.server

opencode 연동

opencode.example.json을 참조하여 mimo-vision을 로컬 stdio MCP 서버로 등록합니다:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mimo-vision": {
      "type": "local",
      "command": ["<你的python路径>", "-m", "mimo_vision_mcp.server"],
      "enabled": true,
      "environment": { "MIMO_API_KEY": "{env:MIMO_API_KEY}" }
    }
  },
  "experimental": { "mcp_timeout": 120000 }
}

참고: experimental.mcp_timeout(기본값 30s)은 MCP 도구 호출 제한 시간을 제어합니다. 비전 요청은 수십 초가 걸릴 수 있으므로 120s 이상으로 설정해야 합니다. mcp.mimo-vision에 timeout을 별도로 설정하면 안 됩니다. mcp_timeout을 덮어써서 제한 시간이 발생할 수 있습니다. 구성 변경 후에는 opencode를 재시작해야 적용됩니다.

이 프로젝트에는 AGENTS.md(텍스트 모델용 호출 가이드)도 포함되어 있습니다. 전역 구성 "instructions": ["<경로>/AGENTS.md"]를 통해 각 세션에 주입하면, 순수 텍스트 모델이 이미지를 만날 때 도구를 능동적으로 호출할 수 있습니다.

도구 설명

images의 각 항목은 다음을 지원합니다:

• 로컬 절대 경로: C:/Users/xx/Pictures/a.png

• 공개 URL: https://example.com/a.jpg

• base64 data URI: data:image/png;base64,....

• 순수 base64 문자열

JSON 반환: { "result": "...", "error": "", "model": "...", "usage": {...} }

WebUI(인터랙티브 프런트엔드 · 원클릭 시작)

초보자 추천 진입점: 그래픽 인터페이스로 이미지 업로드, 모델 선택, 결과 확인이 모두 마우스 조작으로 가능합니다.

원클릭 시작(가장 간단, 어떤 명령도 몰라도 됨)

start-webui.bat 더블클릭(Windows)만 하면 됩니다:

1. 스크립트가 환경을 자동으로 확인/생성하고 의존성을 자동으로 설치합니다

2. 서비스를 자동으로 시작하고 브라우저를 자동으로 엽니다

3. 서비스가 이미 실행 중이면 브라우저만 바로 열고, 중복 실행하지 않습니다

비 Windows 사용자는 수동으로 시작: python -m pip install -e ".[web]" && python -m webui.app를 실행한 후 브라우저에서 http://127.0.0.1:8000을 엽니다(포트는 MIMO_WEBUI_PORT로 변경 가능).

인터페이스 기능

• 상단의 'CLI / MCP 현재 적용 모델'에 명령줄 LLM이 실제로 사용하는 공급업체/모델/스타일이 표시됩니다

• 모델을 선택한 후 **'CLI에 적용(MCP에 동기화)'**을 클릭하면 구성이 .env에 저장되며, 재시작 없이 CLI가 다음 호출부터 새 모델을 사용합니다

• 아래의 '미리보기 테스트(CLI에 영향 없음)'로 먼저 효과를 시험해 볼 수 있습니다

• API Key는 브라우저 localStorage에 저장됩니다. 'CLI에 적용' 시 .env에도 함께 저장할 수 있습니다

테스트

python -m pytest -q

자주 묻는 질문

• 프로그래밍을 못 하거나 명령어를 입력하고 싶지 않으면?: start-webui.bat을 더블클릭하기만 하면 됩니다. 스크립트가 자동으로 .env를 생성하고, 의존성을 설치하고, 서비스를 시작하고, 브라우저를 엽니다. 전 과정이 마우스 조작입니다

• API Key는 어디에 입력하나요?: clone 후에는 .env가 없습니다(저장소에는 빈 템플릿 .env.example만 포함). 시작 스크립트를 더블클릭하면 자동으로 .env가 생성되며, 이후 웹 페이지에서 Key를 입력하고 'CLI에 적용'을 클릭하거나, .env의 MIMO_API_KEY를 직접 편집하면 됩니다

• "API Key가 구성되지 않음" 오류가 반환되는 경우: .env에 MIMO_API_KEY를 구성하거나(또는 WebUI에서 직접 입력하고 'CLI에 적용' 클릭)

• 이미지 형식이 지원되지 않는 경우: JPEG/PNG/GIF/WebP/BMP만 지원됩니다

• base64 입력 시 "구문 분석 실패" 오류가 발생하는 경우: 입력이 유효한 base64이고 형식이 지원 범위 내에 있는지 확인하세요

• MCP 도구 호출 제한 시간 초과: experimental.mcp_timeout을 120000ms 이상으로 설정하세요

라이선스

MIT

참고 자료

• OpenCode Go 문서

• Xiaomi MiMo API 문서

• 이미지 이해 가이드