Image2Flutter MCP

<p align="center"><strong>English</strong> · <a href="docs/README.ko.md">한국어</a> · <a href="docs/README.ja.md">日本語</a> · <a href="docs/README.zh-CN.md">简体中文</a></p>

<p align="center"> <strong>Turn a screenshot into validated, editable Flutter widgets.</strong><br> MCP tools for Codex and Claude, plus a standalone CLI. </p>

<p align="center"> <a href="https://github.com/ezBuilder/image2flutter-mcp/actions/workflows/ci.yml"><img alt="CI: 21 tests passing" src="docs/assets/badge-ci.svg"></a> <a href="https://github.com/ezBuilder/image2flutter-mcp/releases/latest"><img alt="Version 1.1.0" src="docs/assets/badge-version.svg"></a> <a href="#one-command-install"><img alt="Install with one command" src="docs/assets/badge-install.svg"></a> <a href="LICENSE"><img alt="MIT License" src="docs/assets/badge-license.svg"></a> </p>

Image2Flutter reads a UI screenshot, generates real Dart widget code, creates an isolated Flutter project, runs validation, captures a browser render, and produces a visual-diff report. It never ships the whole screenshot as a fake full-screen asset in semantic mode.

Reference → generated Flutter

<table> <tr><th>Reference image</th><th>Flutter web render</th></tr> <tr> <td><img src="docs/assets/video-analysis-reference.png" alt="Reference dashboard" width="430"></td> <td><img src="docs/assets/video-analysis-flutter.png" alt="Generated Flutter dashboard" width="430"></td> </tr> </table>

Both images are 1150×1367. The output is composed from Dart widgets, custom painters, layout primitives, text, and generated visual assets—not a full-screen screenshot overlay. See sample details.

One-command install

Requires Node.js 20+. Flutter is recommended for analyze, test, preview, and visual-diff gates.

curl -fsSL https://raw.githubusercontent.com/ezBuilder/image2flutter-mcp/main/scripts/install.sh | bash

The installer:

• installs the latest stable package globally;
• registers the image2flutter MCP server in Codex and Claude when present;
• allows projects under ~/workspace and ~/Downloads by default;
• runs the version and environment doctor checks;
• enables a safe update check once every 24 hours.

Custom roots:

curl -fsSL https://raw.githubusercontent.com/ezBuilder/image2flutter-mcp/main/scripts/install.sh | \
  IMAGE2FLUTTER_ALLOWED_ROOTS="$HOME/projects:$HOME/designs" bash

Manual npm installation:

npm install --global image2flutter-mcp
image2flutter doctor

Windows PowerShell:

irm https://raw.githubusercontent.com/ezBuilder/image2flutter-mcp/main/scripts/install.ps1 | iex

Use it with an agent

Once installed, attach a screenshot while working in a Flutter/Dart repository and ask:

Recreate this screenshot as editable Flutter widgets. Validate it and show the rendered preview.

The MCP descriptions tell compatible agents to invoke Image2Flutter automatically for screenshot-to-Flutter requests. Six tools cover the full lifecycle:

Tool	Purpose
flutter_ui_convert	End-to-end screenshot conversion and refinement
flutter_ui_materialize	Validate agent-authored Dart without another model call
flutter_ui_preview	Rebuild, render, and compare an existing job
flutter_ui_apply	Copy a verified widget into a Flutter project
flutter_ui_job_get	Inspect manifests, diagnostics, and generated code
flutter_ui_doctor	Verify Flutter, browser, model, and storage readiness

CLI

# Generate an editable semantic widget
image2flutter convert \
  --image ./screen.png \
  --mode semantic \
  --provider auto \
  --responsive adaptive \
  --locale ko-KR \
  --refine 2

# Inspect a job
image2flutter job <job-id> --code

# Re-render and compare
image2flutter preview <job-id>

# Apply only after validation
image2flutter apply <job-id> --project ./my_flutter_app --analyze

Conversion modes

• semantic: editable widgets; rejects a whole-screen screenshot as the implementation.
• hybrid: editable layout plus tightly cropped visual assets where they materially improve fidelity.
• pixel: exact screenshot-backed reproduction for mockups; intentionally not a semantic rebuild.

Model providers

--provider auto prefers the authenticated local Codex CLI, then OPENAI_API_KEY, then MCP sampling from the calling agent. The pipeline itself does not hide model usage: convert may use a model, while materialize, preview, apply, and pixel mode can run without an extra generation call.

Languages and scripts

Visible Unicode text is preserved without automatic translation. The reconstruction prompt handles mixed scripts, CJK glyph fallback, right-to-left direction, locale-sensitive values, emoji, and original line breaks. Set --locale <BCP-47> or MCP locale when the target locale must be explicit; examples include ko-KR, en-US, ja-JP, zh-CN, and ar-SA.

Updates

Installed CLI/MCP entrypoints check the stable release once every 24 hours. When a newer version exists, it is installed globally and used on the next invocation. Network or registry failures never prevent the current command or MCP server from starting.

image2flutter upgrade --check
image2flutter upgrade
IMAGE2FLUTTER_AUTO_UPDATE=0 image2flutter doctor

Output and safety

Each job writes a manifest, Dart source, isolated preview project, render, diff, and validation report under .image2flutter/jobs (or --output). Writes are constrained to IMAGE2FLUTTER_ALLOWED_ROOTS. Applying to a real project requires an explicit flutter_ui_apply/image2flutter apply call, and overwrites remain opt-in.

No API keys, prompts, or screenshots are uploaded by the MCP server unless the selected model provider requires it. Read SECURITY.md before using sensitive designs.

Development

npm ci
npm run check
npm run release:gate

Development happens on develop; main contains released code. See CONTRIBUTING.md, CHANGELOG.md, and the architecture.

한국어 요약

Image2Flutter는 첨부한 UI 이미지를 실제 Dart 위젯으로 재구성하고 Flutter 분석·테스트·웹 렌더·시각 비교까지 수행하는 MCP/CLI입니다. 설치 명령 한 번으로 Codex와 Claude에 등록되며, Flutter 프로젝트에서 이미지를 첨부하고 “그대로 Flutter 위젯으로 만들고 검증해”라고 요청하면 MCP가 자동 선택되도록 도구 설명이 구성되어 있습니다. 전체 화면 이미지를 그대로 붙이는 방식은 semantic 모드에서 허용하지 않습니다.

License

MIT © 2026 ezBuilder