agy-image-mcp

中文 | English

讓 Claude Code 用你的 Google AI Pro 訂閱生圖 —— 不需要 Gemini API key，也不用按張付費。

這是一個 MCP server（MCP 是讓 Claude 使用新工具的標準方式），包裝 Google 官方的 Antigravity CLI（agy）。 Claude 會拆解需求、寫 prompt、生圖、看預覽圖檢查、不滿意就自己修改重試，最後交出精確尺寸的成品。

目前版本：1.0.0（更新紀錄）

主要功能

• 🆓 用訂閱配額生圖：走 Google AI Pro 的訂閱額度，不需要 API key，沒有每張圖的費用。

• 🛡️ 只用官方工具：只呼叫官方 agy 執行檔，不讀取登入憑證、不呼叫任何私有 API。

• 📐 尺寸精確：自動選最接近的長寬比，再裁切成你要的像素尺寸（例如 1080×1350），不靠 AI 目測。

• 👀 Claude 自己檢查、自己重試：Claude 看縮小的預覽圖判斷（省 token），不符需求就修改 prompt 重試；每張圖最多 3 次，超過會停下來問你。

• ✍️ 文字後製，不靠 AI 寫字：生圖模型寫中文常出錯，所以標題、標語由 Claude 用 Noto Sans 排上去，生圖時會先保留留白；背景的小字則不強求去除。

• 📊 配額看得到：生圖前先查剩餘配額（不消耗配額，用完就不啟動、不計次數），並告訴你還要等多久。

• ⏱️ 不卡住、不空等：執行中一偵測到配額用盡就立刻停下回報；圖片一生好就結束，一張約 30–60 秒。

• ✅ 有自動化測試：附離線測試（不耗配額）與實機生圖測試。

Related MCP server: Image MCP

運作方式

快速開始

需要：Windows 10/11、Python 3.10 以上、Git、Claude Code（需要終端機版的 claude 指令）、 付費的 Google AI Pro 訂閱。

第一次安裝建議照 DEPLOY.md 逐步做：它多了每一步的確認方式、設定檔範例與疑難排解。以下是快速版。

1. 安裝並登入 agy（Google 官方安裝腳本，會驗證檔案雜湊）：

irm https://antigravity.google/cli/install.ps1 | iex

裝完開一個新的 PowerShell 視窗，執行 agy，在瀏覽器用 Google AI Pro 帳號登入。接下來的指令都在這個新視窗執行。

2. 下載本專案並安裝：

git clone https://github.com/sshenwen-glitch/agy-image-mcp.git C:\tools\agy-image-mcp
cd C:\tools\agy-image-mcp
python -m venv .venv
.venv\Scripts\python.exe -m pip install -r requirements.txt
.venv\Scripts\python.exe tests\test_acceptance.py   # 離線測試，不耗配額

3. 註冊到 Claude Code：

claude mcp add agy-image --scope user `
  -- "C:\tools\agy-image-mcp\.venv\Scripts\python.exe" "C:\tools\agy-image-mcp\server.py"

註冊後可用 claude mcp get agy-image 確認顯示 Connected。接著：

4. 拉長工具逾時：每張圖約 30–60 秒。編輯 %USERPROFILE%\.claude\settings.json：

   • 檔案不存在 → 新建，內容只放：

     {
       "env": { "MCP_TOOL_TIMEOUT": "360000" }
     }

   • 檔案已存在 → 在最外層 { } 裡加一行 "env": { "MCP_TOOL_TIMEOUT": "360000" }，和前一行之間要有逗號； 原本已有 "env" 時，改把 "MCP_TOOL_TIMEOUT": "360000" 加進去。不要整個覆蓋。

5. 套用生圖規則：把 CLAUDE_SNIPPET.md 貼進 %USERPROFILE%\.claude\CLAUDE.md（沒有就新建），並把其中的 <repo> 換成 C:\tools\agy-image-mcp。

6. （選用）下載字型讓 Claude 自動排標題：把 NotoSansTC[wght].ttf 放到 C:\tools\agy-image-mcp\fonts\（fonts 資料夾要先建立；用 PowerShell 複製時請用 Copy-Item -LiteralPath，否則 [wght] 會被當成萬用字元）。

7. 重開 Claude Code：在 Claude Code 輸入 /exit（或關閉終端機），再重新執行 claude。Claude 要重開後才會載入工具與規則。

使用方式

裝好後，在 Claude Code 直接用平常的話提出需求即可，例如：

• 「幫我做一張 1080×1350 的店家公告底圖，主題是颱風天照常營業，標題寫『颱風天照常營業』」

• 「生一張 1920×1080 的網站橫幅，咖啡廳的早晨氛圍，左側留白放標語」

• 「做一張 1080×1080 的 IG 貼文，夏季冰飲主題，不用文字」

Claude 會：

1. 把需求整理成 prompt，呼叫生圖工具（工具會自動先查配額，用完就直接告訴你要等多久）。

2. 生圖後看預覽圖逐項檢查，不符合就修改重試（最多 3 次，超過會先問你）。

3. 有標題時，用 Noto Sans 把文字排到預留的位置（需先完成快速開始第 6 步；沒有字型時會交付底圖並列出要放的文字）。

4. 回報成品路徑。

圖片存在 %USERPROFILE%\agy-images\<job_id>\（可用 AGY_IMAGE_OUT_DIR 更改）：final_<n>.png 是成品，final_<n>_text.png 是排好字的版本。

沒指定尺寸時預設 1080×1350（4:5 社群直式）。想知道還剩多少配額，可以直接問 Claude「生圖配額還剩多少？」。

限制

• 只在 Windows 上驗證過；只在 Claude Code 上測試過。

• 每張約 30–60 秒（agy 啟動偶爾更慢）。不同的圖可以同時生成；同一張圖的重試會依序進行。同時生成多張時配額消耗也會加快。

• 尺寸上限預設每邊 8192 px（AGY_IMAGE_MAX_SIDE 可調整）。

• 生圖模型的輸出比例是固定的幾種，會再裁切成你要的尺寸。常見尺寸（例如 1080×1350）約裁掉 7% 的畫面； 少見的比例會裁更多，回傳的 crop_loss_pct 會顯示實際比例。

• 標題文字不由 AI 畫，一律後製；背景招牌上的文字可能是錯亂的字。

• 生圖次數受你的 Google AI Pro 配額限制。配額分成 Gemini Models（Flash／Pro 共用）、Gemini 4 Argon、 Claude and GPT models 三個群組，各有每週與 5 小時上限；生圖用的是 Gemini Models。

安全性

• 本工具只執行 Google 官方的 agy，不讀取你的登入憑證，也不呼叫任何未公開的 API。

• 請了解這個信任前提：agy 必須以「自動核准」模式執行（--dangerously-skip-permissions），因為背景執行時沒辦法逐一詢問你。 這代表 agy 的 AI 代理在執行期間可以自動使用它的所有工具，本工具只能降低、無法完全杜絕風險：

  • 加上 --sandbox：限制終端機指令（但實測曾有指令仍被執行，因此另有下方的回報機制）。

  • 給 agy 的指示只要求生圖，不要它讀寫檔案或執行指令；--add-dir 只額外加入該次生圖的資料夾，但不保證 agy 碰不到其他檔案。

  • 只接受 agy 這次在自己資料夾產生的新圖片，不會因為 agy 回覆了某個路徑就搬動你的檔案。

  • 參考圖（ref_images）只接受真正的圖片檔，避免其他檔案被一併送出。

  • agy 執行了終端機指令（agy_ran_commands）或用到生圖以外的工具（agy_unexpected_tools）時，結果中會列出，方便你檢查。

• 建議只在你信任的電腦與帳號上使用，並留意上述回報。

常見問題

會不會被 Google 停權？ 本工具只透過官方 CLI 操作，和你自己在終端機使用 agy 相同。但服務條款由 Google 決定，請自行確認並遵守 Antigravity 的服務條款。

可以生幾張？ 依你的 Google AI Pro 配額而定。問 Claude「生圖配額還剩多少？」就會顯示各群組剩餘百分比與重置時間。 某個對話模型的群組用完時，可改 AGY_MODEL 換到另一個群組（見環境變數）。

需要付費嗎？ 需要有付費的 Google AI Pro 訂閱；除此之外不需額外付費，生圖使用的是訂閱內的額度。

能用在 macOS / Linux 或 Claude Desktop 嗎？ 程式本身不限平台，但目前只在 Windows + Claude Code 上驗證過，其他環境可能需要調整。

疑難排解

其他狀況（配額用盡、BUSY、排字超出圖片等）見 DEPLOY.md 疑難排解。

更新與移除

• 更新：git pull 後重新安裝套件、跑測試、重開 Claude Code；若 CHANGELOG 註明規則有更新，也要重新貼上 CLAUDE_SNIPPET.md。步驟見 DEPLOY.md 更新。

• 移除：claude mcp remove agy-image -s user，再刪除設定與資料夾。步驟見 DEPLOY.md 移除。

回報問題

歡迎到 GitHub Issues 回報，請附上：

• 問 Claude「執行 image_status」得到的結果（含本工具與 agy 的版本）

• 發生了什麼、你預期的結果、錯誤訊息（error_type 與 message）

• 相關的 log：%USERPROFILE%\agy-images\<job_id>\agy_log_<n>.ndjson 與 agy_cli_<n>.log

⚠️ log 裡會有你的 prompt、檔案路徑與 Google 帳號 email，貼上前請先檢查並刪掉不想公開的內容。

本專案為個人開源專案，與 Google 無關。

進階

提供的工具

完整的參數、回傳欄位與錯誤類型見 SPEC.md 第 3 節。

生圖規則

CLAUDE_SNIPPET.md 是給 Claude 的生圖流程規則（拆需求、檢查重點、重試與錯誤處理、文字後製），部署時貼進 CLAUDE.md。

文字後製腳本

scripts/add_title.py 在底圖上方排主標與副標，Claude 會自動呼叫，也可以手動使用（在專案資料夾內執行）：

.venv\Scripts\python.exe scripts\add_title.py final_1.png out.png `
  --font "fonts\NotoSansTC[wght].ttf" --title "標題文字" --subtitle "副標文字"

標題過長會自動換行（主標盡量 2 行內、避免在詞中間斷行），也可以用 \n 指定換行位置；顏色可寫 #RGB 或 #RRGGBB。 文字超出圖片時會印出 overflow=true 並以結束碼 3 結束（圖仍會存檔）。全部參數見 --help。

環境變數

環境變數在註冊時用 -e 設定，例如 claude mcp add agy-image --scope user -e AGY_IMAGE_OUT_DIR="D:\my-images" -- ...。

輸出結構

<AGY_IMAGE_OUT_DIR>/
├── state.json                 # 各 job 嘗試次數、429 重置時間（state.lock 用於多個工作階段同時寫入）
├── .locks/<job_id>.lock       # 同一個 job 的跨工作階段鎖（過期的會隨舊 log 一起清掉）
└── <job_id>/
    ├── raw_<n>.*              # agy 原始輸出（jpg/png/webp）
    ├── final_<n>.png          # 精確尺寸成品
    ├── preview_<n>.png        # 長邊 ≤1024，給 Claude 檢查用
    ├── final_<n>_text.png     # 排好標題的版本（有後製文字時）
    ├── final_<n>_text_preview.png  # 排字版的預覽圖
    ├── ref_<n>_<i>.*          # 參考圖副本（有提供時）
    ├── agy_log_<n>.ndjson     # agy 的 stream-json 紀錄
    └── agy_cli_<n>.log        # agy 內部 log（用於偵測配額用盡）

參與開發

測試、重新產生流程圖、修改時要同步哪些檔案、發布流程，見 CONTRIBUTING.md。 規格與設計決策見 SPEC.md，開發與驗收過程見 docs/DEVELOPMENT_LOG.md。

授權

MIT License