Gpt Image MCP

🚀 圖像生成MCP服務器

圖像生成MCP服務器旨在為AI聊天機器人賦能，實現通用的圖像生成功能。傳統的AI聊天機器人界面，無論其底層語言模型多麼強大，通常都侷限於純文本交互。而本服務器通過標準化的模型上下文協議（MCP），使任何基於大語言模型（LLM）的聊天機器人客戶端都能生成專業品質的圖像。

🚀 快速開始

前提條件

• Python 3.10及以上版本
• UV包管理器
• OpenAI API密鑰（用於OpenAI模型）
• Google Gemini API密鑰（用於Gemini模型，可選）

安裝步驟

1. 克隆並設置項目：

git clone <repository-url>
cd image-gen-mcp
uv sync

注意：本項目使用UV進行快速、可靠的Python包管理。與傳統的pip/venv工作流相比，UV提供了更好的依賴解析、更快的安裝速度和更完善的環境隔離。

2. 配置環境：

cp .env.example .env
# 編輯.env文件並添加你的API密鑰：
# - PROVIDERS__OPENAI__API_KEY用於OpenAI模型
# - PROVIDERS__GEMINI__API_KEY用於Gemini模型（可選）

3. 測試設置：

uv run python scripts/dev.py setup
uv run python scripts/dev.py test

運行服務器

開發模式

# 用於Web開發和測試的HTTP傳輸
./run.sh dev

# 帶有開發工具（Redis Commander）的HTTP傳輸
./run.sh dev --tools

# 用於Claude Desktop集成的STDIO傳輸
./run.sh stdio

# 帶有監控的生產部署
./run.sh prod

手動執行

# STDIO傳輸（默認） - 用於Claude Desktop
uv run python -m gpt_image_mcp.server

# HTTP傳輸 - 用於Web部署
uv run python -m gpt_image_mcp.server --transport streamable-http --port 3001

# SSE傳輸 - 用於即時應用程序
uv run python -m gpt_image_mcp.server --transport sse --port 8080

# 自定義配置
uv run python -m gpt_image_mcp.server --config /path/to/.env --log-level DEBUG

# 為Web開發啟用CORS
uv run python -m gpt_image_mcp.server --transport streamable-http --cors

命令行選項

uv run python -m gpt_image_mcp.server --help

Image Gen MCP Server - 使用OpenAI的gpt-image-1模型生成和編輯圖像

選項:
  --config PATH         配置文件的路徑（.env格式）
  --log-level LEVEL     設置日誌級別（DEBUG, INFO, WARNING, ERROR, CRITICAL）
  --transport TYPE      傳輸方法（stdio, sse, streamable-http）
  --port PORT          HTTP傳輸的端口（默認值: 3001）
  --host HOST          HTTP傳輸的主機地址（默認值: 127.0.0.1）
  --cors               為Web部署啟用CORS
  --version            顯示版本信息
  --help               顯示幫助信息

示例:
  # Claude Desktop集成
  uv run python -m gpt_image_mcp.server

  # 帶有Redis緩存的Web部署
  uv run python -m gpt_image_mcp.server --transport streamable-http --port 3001

  # 帶有調試日誌和工具的開發模式
  uv run python -m gpt_image_mcp.server --log-level DEBUG --cors

MCP客戶端集成

本服務器可與任何支持MCP的聊天機器人客戶端配合使用。以下是配置示例：

Claude Desktop（Anthropic）

{
  "mcpServers": {
    "image-gen-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/image-gen-mcp",
        "run",
        "image-gen-mcp"
      ],
      "env": {
        "OPENAI_API_KEY": "your-api-key-here"
      }
    }
  }
}

Continue.dev（VS Code擴展）

{
  "mcpServers": {
    "gpt-image": {
      "command": "uv",
      "args": ["--directory", "/path/to/image-gen-mcp", "run", "image-gen-mcp"],
      "env": {
        "OPENAI_API_KEY": "your-api-key-here"
      }
    }
  }
}

自定義MCP客戶端

對於其他支持MCP的應用程序，使用標準的MCP STDIO傳輸：

uv run python -m gpt_image_mcp.server

通用兼容性：本服務器遵循標準的MCP協議，確保與當前和未來支持MCP的客戶端在整個AI生態系統中兼容。

✨ 主要特性

🎨 多供應商圖像生成

• 多種AI模型：支持OpenAI（gpt-image-1、dall-e-3、dall-e-2）和Google Gemini（imagen-4、imagen-4-ultra、imagen-3）的圖像生成模型。
• 文本到圖像：根據文本描述生成高質量圖像。
• 圖像編輯：使用文本指令編輯現有圖像（OpenAI模型支持）。
• 多種格式：支持PNG、JPEG和WebP輸出格式。
• 質量控制：提供自動、高、中、低四種質量設置。
• 背景控制：支持透明、不透明或自動背景選項。
• 動態模型發現：在運行時查詢可用的模型和功能。

🔗 MCP集成

• FastMCP框架：基於最新的MCP Python SDK構建。
• 多種傳輸方式：支持STDIO、HTTP和SSE傳輸。
• 結構化輸出：使用正確的模式驗證工具響應。
• 資源訪問：提供用於圖像檢索和管理的MCP資源。
• 提示模板：內置10多種常見用例的提示模板。

💾 存儲與緩存

• 本地存儲：具有組織良好的目錄結構和元數據。
• 基於URL的訪問：生成支持傳輸的圖像URL。
• 雙重訪問：即時提供Base64數據和持久的資源URI。
• 智能緩存：基於內存的緩存，支持TTL和Redis。
• 自動清理：可配置文件保留策略。

🚀 生產部署

• Docker支持：提供適用於生產環境的Docker容器。
• 多傳輸方式：支持用於Claude Desktop的STDIO和用於Web部署的HTTP。
• 反向代理：使用Nginx進行反向代理，並配置速率限制。
• 監控：集成Prometheus和Grafana進行監控。
• SSL/TLS：使用Certbot自動管理證書。

🛠️ 開發特性

• 類型安全：使用Pydantic模型提供完整的類型提示。
• 錯誤處理：全面的錯誤處理和日誌記錄。
• 配置管理：基於環境變量的配置管理。
• 測試：基於Pytest的測試套件，支持異步測試。
• 開發工具：支持熱重載、Redis Commander和調試日誌。

📦 安裝指南

克隆項目

git clone <repository-url>
cd image-gen-mcp

安裝依賴

uv sync

配置環境

cp .env.example .env
# 編輯.env文件並添加API密鑰

測試安裝

uv run python scripts/dev.py setup
uv run python scripts/dev.py test

💻 使用示例

基礎用法

# 通過MCP客戶端使用
result = await session.call_tool(
    "generate_image",
    arguments={
        "prompt": "A beautiful sunset over mountains, digital art style",
        "quality": "high",
        "size": "1536x1024",
        "style": "vivid"
    }
)

高級用法

使用提示模板

# 獲取針對社交媒體優化的提示
prompt_result = await session.get_prompt(
    "social_media_prompt",
    arguments={
        "platform": "instagram",
        "content_type": "product announcement",
        "brand_style": "modern minimalist"
    }
)

訪問生成的圖像

# 通過資源URI訪問
image_data = await session.read_resource("generated-images://img_20250630143022_abc123")

# 查看最近的圖像
history = await session.read_resource("image-history://recent?limit=5")

# 存儲統計信息
stats = await session.read_resource("storage-stats://overview")

📚 詳細文檔

可用工具

list_available_models

列出所有可用的圖像生成模型及其功能。

返回值：包含模型信息、功能和供應商詳細信息的字典。

generate_image

使用任何支持的模型根據文本描述生成圖像。

參數：

• prompt（必需）：所需圖像的文本描述。
• model（可選）：要使用的模型（例如，"gpt-image-1"、"dall-e-3"、"imagen-4"）。
• quality："auto" | "high" | "medium" | "low"（默認值："auto"）。
• size："1024x1024" | "1536x1024" | "1024x1536"（默認值："1536x1024"）。
• style："vivid" | "natural"（默認值："vivid"）。
• output_format："png" | "jpeg" | "webp"（默認值："png"）。
• background："auto" | "transparent" | "opaque"（默認值："auto"）。

注意：參數的可用性取決於所選的模型。使用list_available_models檢查功能。

edit_image

使用文本指令編輯現有圖像。

參數：

• image_data（必需）：Base64編碼的圖像或數據URL。
• prompt（必需）：編輯指令。
• mask_data：可選的掩碼，用於有針對性的編輯。
• size、quality、output_format：與generate_image相同。

可用資源

• generated-images://{image_id} - 訪問特定的生成圖像。
• image-history://recent - 瀏覽最近的生成歷史記錄。
• storage-stats://overview - 存儲使用情況和統計信息。
• model-info://gpt-image-1 - 模型功能和定價信息。

提示模板

內置了適用於常見用例的提示模板：

• 創意圖像：用於藝術圖像生成。
• 產品攝影：用於商業產品圖像。
• 社交媒體圖形：針對特定平臺優化的帖子。
• 博客標題：文章標題圖像。
• OG圖像：社交媒體預覽圖像。
• 英雄橫幅：網站英雄部分的圖像。
• 電子郵件標題：時事通訊標題。
• 視頻縮略圖：YouTube/視頻縮略圖。
• 信息圖表：數據可視化圖像。
• 藝術風格：特定藝術運動風格。

配置

通過環境變量或.env文件進行配置：

# =============================================================================
# 供應商配置
# =============================================================================
# OpenAI供應商（默認啟用）
PROVIDERS__OPENAI__API_KEY=sk-your-openai-api-key-here
PROVIDERS__OPENAI__BASE_URL=https://api.openai.com/v1
PROVIDERS__OPENAI__ORGANIZATION=org-your-org-id
PROVIDERS__OPENAI__TIMEOUT=300.0
PROVIDERS__OPENAI__MAX_RETRIES=3
PROVIDERS__OPENAI__ENABLED=true

# Gemini供應商（默認禁用）
PROVIDERS__GEMINI__API_KEY=your-gemini-api-key-here
PROVIDERS__GEMINI__BASE_URL=https://generativelanguage.googleapis.com/v1beta/
PROVIDERS__GEMINI__TIMEOUT=300.0
PROVIDERS__GEMINI__MAX_RETRIES=3
PROVIDERS__GEMINI__ENABLED=false
PROVIDERS__GEMINI__DEFAULT_MODEL=imagen-4

# =============================================================================
# 圖像生成設置
# =============================================================================
IMAGES__DEFAULT_MODEL=gpt-image-1
IMAGES__DEFAULT_QUALITY=auto
IMAGES__DEFAULT_SIZE=1536x1024
IMAGES__DEFAULT_STYLE=vivid
IMAGES__DEFAULT_MODERATION=auto
IMAGES__DEFAULT_OUTPUT_FORMAT=png
# 圖像託管的基礎URL（例如，https://cdn.example.com用於nginx/CDN）
IMAGES__BASE_HOST=

# =============================================================================
# 服務器配置
# =============================================================================
SERVER__NAME=Image Gen MCP Server
SERVER__VERSION=0.1.0
SERVER__PORT=3001
SERVER__HOST=127.0.0.1
SERVER__LOG_LEVEL=INFO
SERVER__RATE_LIMIT_RPM=50

# =============================================================================
# 存儲配置
# =============================================================================
STORAGE__BASE_PATH=./storage
STORAGE__RETENTION_DAYS=30
STORAGE__MAX_SIZE_GB=10.0
STORAGE__CLEANUP_INTERVAL_HOURS=24

# =============================================================================
# 緩存配置
# =============================================================================
CACHE__ENABLED=true
CACHE__TTL_HOURS=24
CACHE__BACKEND=memory
CACHE__MAX_SIZE_MB=500
# CACHE__REDIS_URL=redis://localhost:6379

部署

生產部署

服務器支持使用Docker、監控和反向代理進行生產部署：

# 快速生產部署
./run.sh prod

# 手動使用Docker Compose部署
docker-compose -f docker-compose.prod.yml up -d

生產環境棧包括：

• 圖像生成MCP服務器：主應用程序容器。
• Redis：用於緩存和會話存儲。
• Nginx：帶有速率限制的反向代理（單獨配置）。
• Prometheus：指標收集。
• Grafana：監控儀表盤。

訪問點：

• 主服務：http://localhost:3001（通過代理）
• Grafana儀表盤：http://localhost:3000
• Prometheus：http://localhost:9090（僅本地訪問）

VPS部署

對於使用SSL、監控和生產加固的VPS部署：

# 下載部署腳本
wget https://raw.githubusercontent.com/your-repo/image-gen-mcp/main/deploy/vps-setup.sh
chmod +x vps-setup.sh
./vps-setup.sh

包括的功能：

• Docker容器化。
• 帶有SSL的Nginx反向代理。
• 自動證書管理（Certbot）。
• 系統監控和日誌記錄。
• 防火牆配置。
• 自動備份。

詳細說明請參閱VPS部署指南。

Docker配置

可用的Docker Compose配置文件：

# 使用HTTP傳輸的開發模式
docker-compose -f docker-compose.dev.yml up

# 帶有Redis Commander的開發模式
docker-compose -f docker-compose.dev.yml --profile tools up

# 用於桌面集成的STDIO傳輸
docker-compose -f docker-compose.dev.yml --profile stdio up

# 帶有監控的生產模式
docker-compose -f docker-compose.prod.yml up -d

🔧 技術細節

架構

本服務器採用模塊化、適用於生產環境的架構：

核心組件：

• 服務器層 (server.py)：基於FastMCP的MCP服務器，支持多種傳輸方式。
• 配置 (config/)：基於環境變量的設置管理，並進行驗證。
• 工具層 (tools/)：提供圖像生成和編輯功能。
• 資源層 (resources/)：用於數據訪問和模型註冊的MCP資源。
• 存儲管理器 (storage/)：有組織的本地圖像存儲，並支持清理功能。
• 緩存管理器 (utils/cache.py)：基於內存和Redis的緩存系統。

多供應商架構：

• 供應商註冊表 (providers/registry.py)：集中管理供應商和模型。
• 供應商基類 (providers/base.py)：所有供應商的抽象基類。
• OpenAI供應商 (providers/openai.py)：集成OpenAI API，並具備重試邏輯。
• Gemini供應商 (providers/gemini.py)：集成Google Gemini API。
• 類型系統 (types/)：使用Pydantic模型確保類型安全。
• 驗證 (utils/validators.py)：輸入驗證和清理。

基礎設施：

• 提示模板 (prompts/)：用於優化提示的模板系統。
• 動態模型發現：在運行時檢測模型功能。
• 參數轉換：自動映射不同供應商之間的參數。

部署：

• Docker支持：提供開發和生產環境的容器。
• 多傳輸方式：支持STDIO、HTTP和SSE傳輸層。
• 監控：集成Prometheus指標和Grafana儀表盤。
• 反向代理：使用Nginx進行反向代理，支持SSL和速率限制。

成本估算

服務器提供操作成本估算：

• 文本輸入：每100萬個令牌約5美元。
• 圖像輸出：每100萬個令牌約40美元（每張圖像約1750個令牌）。
• 典型成本：每次圖像生成約0.07美元。

錯誤處理

全面的錯誤處理包括：

• API速率限制和重試。
• 無效參數驗證。
• 存儲錯誤恢復。
• 緩存故障回退。
• 詳細的錯誤日誌記錄。

安全

安全功能包括：

• 保護OpenAI API密鑰。
• 輸入驗證和清理。
• 文件系統訪問控制。
• 速率限制保護。
• 日誌中不暴露憑證。

📄 許可證

本項目採用MIT許可證，詳情請參閱LICENSE文件。

貢獻指南

1. 分叉倉庫。
2. 創建功能分支。
3. 進行更改。
4. 為新功能添加測試。
5. 運行測試套件。
6. 提交拉取請求。

支持

如果遇到問題或有疑問：

1. 查看故障排除指南。
2. 查看常見問題。
3. 在GitHub上創建問題。

可視化展示

實際使用場景

Claude Desktop通過MCP集成無縫生成圖像

生成示例

*通過MCP服務器生成的高質量圖像，展示了專業級的輸出效果*

使用案例與應用場景

🎯 內容創作工作流程

• 博主和作家：直接在寫作工具中生成自定義插圖。
• 社交媒體經理：在聊天界面內創建特定平臺的圖形，無需切換工具。
• 營銷團隊：在頭腦風暴會議期間快速原型化視覺概念。
• 教育工作者：按需生成教學材料和視覺輔助工具。

🚀 開發與設計

• UI/UX設計師：在設計討論期間快速生成原型。
• 前端開發人員：在開發環境中使用佔位符和概念圖像。
• 技術文檔撰寫人員：為文檔生成自定義圖表和插圖。
• 產品經理：在任何基於LLM的工具中進行視覺概念溝通。

🏢 企業集成

• 客戶支持：生成可視化解釋和指南。
• 銷售團隊：根據客戶需求定製演示材料。
• 培訓項目：在對話界面中創建視覺學習材料。
• 內部工具：為現有的基於LLM的應用程序添加圖像生成功能。

🎨 創意產業

• 遊戲開發者：進行概念藝術和資產構思。
• 電影和媒體：進行故事板和概念可視化。
• 建築行業：快速生成視覺參考和情緒板。
• 廣告行業：進行廣告活動概念開發。

關鍵優勢：與特定平臺的解決方案不同，這種通用方法意味著您的圖像生成功能可以在不同的工具和工作流程中使用，消除了供應商鎖定，最大限度地提高了工作效率。

AI集成的未來

模型上下文協議代表了向標準化AI工具集成的範式轉變。隨著越來越多的LLM客戶端採用MCP支持，像本服務器這樣的工具將在整個生態系統中發揮越來越重要的作用，提供通用的功能。

當前MCP採用情況：

• ✅ Claude Desktop（Anthropic） - 全面支持MCP。
• ✅ Continue.dev - 集成了MCP的VS Code擴展。
• ✅ Zed Editor - 內置MCP支持，適用於編碼工作流程。
• 🚀 不斷發展的生態系統 - 新的客戶端不斷採用MCP。

願景：未來，AI功能將變得模塊化、可互操作且由用戶控制，而不是侷限於特定平臺。

---

🌟 構建通用AI生態系統

通過模型上下文協議的力量，在所有平臺上實現高級AI功能的民主化。一臺服務器，無限可能。