Skip to main content
Glama
Sign In
deenesjakoruzh
mimo-vision-mcp

mimo-vision-mcp

by mikulovesuki
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

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 등의 도구를 능동적으로 호출하여 비전 기능을 얻을 수 있습니다.

Python License CI

🚀 원클릭 시작(초보자도 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: vision-bridge-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를 실시간으로 다시 읽습니다):

변수

설명

기본값

MIMO_API_KEY

API Key(OPENAI_API_KEY도 사용 가능)

비어 있음

MIMO_PROVIDER

공급업체 ID

opencode-go

MIMO_MODEL

비전 모델 ID

mimo-v2.5

MIMO_BASE_URL

OpenAI 호환 엔드포인트

https://opencode.ai/zen/go/v1

MIMO_API_STYLE

chat / responses(비어 있으면 자동)

자동

MIMO_MAX_TOKENS

단일 출력 상한

4096

MIMO_TIMEOUT

요청 제한 시간(초)

120

비전 모델 전환: 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"]를 통해 각 세션에 주입하면, 순수 텍스트 모델이 이미지를 만날 때 도구를 능동적으로 호출할 수 있습니다.

도구 설명

도구

설명

analyze_image(images, prompt, detail?)

일반 이미지 질의응답, 다중 이미지 가능

describe_image(images, detail?)

이미지 내용을 상세하게 설명

extract_text_from_image(images, detail?)

이미지 속 텍스트 추출(OCR)

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

참고 자료

Available Tools

3 tools
analyze_imageA

分析图片内容并回答你的问题（基于视觉模型）。

当用户要求"看图片/描述图片/识别图中内容/截图分析"，或对话中出现本地图片路径、 图片 URL 或 base64 图片数据时，主动调用本工具。

Args: images: 图片列表，每项可以是： - 本地绝对路径，如 "C:/Users/xx/Pictures/a.png" - 公网 URL，如 "https://example.com/a.jpg" - base64 data URI，如 "data:image/png;base64,...." - 纯 base64 字符串 prompt: 对图片提出的问题或指令，如 "这张图里有什么动物？" detail: 可选，图片采样精细度，取 "low" / "high" / "auto"

NameRequiredDescriptionDefault
detailNo
imagesYes
promptYes

Output Schema

NameRequiredDescription
resultYes

TDQS

A3.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

无注解，描述承担全部行为披露责任。仅提到'基于视觉模型'暗示外部调用，但未说明网络依赖、图片大小限制、失败处理或隐私影响等关键行为。描述只覆盖输入格式，行为细节缺失。

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

描述采用分节结构（触发条件+参数解释），信息密集且无冗余。中文表述流畅，但长度稍长，每句均有价值，整体简洁。

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

工具中等复杂，有输出schema故无需描述返回值。描述覆盖了参数和触发场景，但未提及错误处理或资源限制等潜在注意事项，在有无注解情况下仍可更完整。

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

schema覆盖率为0%，描述完全弥补了参数含义：详细列出images的四种合法格式（路径、URL、data URI、纯base64），解释prompt用途，并明确detail为采样精细度且枚举值low/high/auto。超越schema预期。

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

描述明确说明工具是'分析图片内容并回答你的问题'，使用具体动词和资源。但未明确区分与兄弟工具describe_image、extract_text_from_image的边界，可能混淆，因此扣一分。

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

描述提供了明确的触发条件（用户要求看图片/描述图片等或出现图片路径/URL/base64），并指示'主动调用'。但未说明何时不使用（如仅需纯描述时是否应选describe_image），不过整体指引清晰。

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

describe_imageA

详细描述图片内容（基于视觉模型）。

当用户要求"描述/介绍一下这张图、看到什么"时调用。输入约定同 analyze_image。

NameRequiredDescriptionDefault
detailNo
imagesYes

Output Schema

NameRequiredDescription
resultYes

TDQS

A3.5/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full responsibility. It mentions '基于视觉模型' (vision model based) but does not elaborate on output format, limitations, or side effects. It also references '输入约定同 analyze_image' without specifying those conventions, leaving behavior opaque. Some context is given but insufficient for a fully transparent description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very concise: two sentences, no fluff, directly states purpose and when to call. It is well-structured with a clear trigger and a reference for input conventions. However, the conciseness comes at the cost of completeness, but for the dimension of conciseness and structure, it is efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description fails to provide comprehensive guidance: no exclusions, no detail on output, no mention of what happens for invalid input, and no standalone parameter explanation. The context signals show no annotations and 0% parameter coverage, so the description must compensate but only partially does by reusing analyze_image's conventions. For a simple tool this may be acceptable, but for an AI agent making decisions, it's insufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, meaning no parameter descriptions are provided in the schema. The description mentions '输入约定同 analyze_image' which implies conventions are shared, but since analyze_image's conventions are not spelled out here, the agent must look elsewhere. The description lists only 'detail' and 'images' names without explanation. This adds minimal clarity, and the description does not compensate for the missing parameter docs.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's action ('详细描述图片内容' = describe image content in detail) and specifically mentions the vision model basis. While it doesn't explicitly contrast with sibling tools, the phrasing '当用户要求...' distinguishes it from extract_text_from_image which focuses on text extraction. Purpose is clear and specific.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit trigger conditions ('当用户要求描述/介绍一下这张图、看到什么时调用') and points to analyze_image for input conventionsastra. However, it does not mention exclusions or when to prefer extract_text_from_image over this tool, so some guidance is missing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

extract_text_from_imageA

提取图片中的文字（OCR，基于视觉模型）。

当用户要求"识别/提取图中文字、截图里的文本"时调用。输入约定同 analyze_image。

NameRequiredDescriptionDefault
detailNo
imagesYes

Output Schema

NameRequiredDescription
resultYes

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It adds that it's 'OCR based on vision model', which gives some insight into how it works. However, it does not disclose potential limitations, error behavior, or whether images are stored, leaving some behavioral aspects unspecified. The read-only nature mitigates the gap, but the description is thin.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise, two sentences, with the main purpose front-loaded. Every sentence adds value, and there is no wasted wording. The reference to analyze_image is efficient, though it creates a dependency.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema is present, so return values are covered externally. The description covers purpose and usage trigger. The only gap is that it relies on the sibling tool for input conventions, but given the tool's simplicity and the presence of sibling context, it is adequately complete for an OCR tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It only says 'input conventions same as analyze_image' without explaining what images or detail mean in practice. This is a pointer to sibling information rather than an explanation, failing to provide direct parameter semantics for the agent.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool extracts text from images via OCR with a specific verb and resource. It also distinguishes from sibling tools by explicitly mentioning when to use it for 'recognize/extract text in images, screenshots', which sets it apart from analyze_image and describe_image.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides an explicit trigger condition: 'Call when user asks to recognize/extract text in images'. It also references input conventions from analyze_image, giving clear context. However, it does not explicitly mention when not to use this tool, though the sibling distinction is implicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv0.1.0
    • First observedanalyze_image
    • First observeddescribe_image
    • First observedextract_text_from_image
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.6/5.0

Scored across 3 tools

Disambiguation2/5

The tools analyze_image and describe_image have overlapping purposes—both process images to provide content understanding, and analyze_image accepts a prompt that could easily request a description. This creates selection ambiguity, while extract_text_from_image is clearly distinct.

Naming Consistency5/5

All tool names follow the consistent verb_noun pattern: analyze_image, describe_image, extract_text_from_image. The naming is predictable and makes functionality intuitively obvious.

Tool Count4/5

With only 3 tools, the server stays within the typical 3-15 range and is appropriately scoped for a vision analysis service. Each tool addresses a high-level need without excessive bloat.

Completeness3/5

The set covers core image understanding (general Q&A, full description, OCR), but lacks dedicated tools for tasks like classification, comparison, or object detection. The overlap between analyze and describe indicates a design gap, though the current coverage handles basic workflows.

Resources

Related MCP Connectors

Related MCP Servers