mcp-apple-image-playground

<p align="center"> <img src="assets/banners/banner.png" alt="Apple Image MCP — On-device AI image generation for macOS" width="100%"> </p> <p align="center"> <strong>AI image generation for macOS via Image Playground. 17 tools. Zero API keys.</strong><br> On-device styles (animation, illustration, sketch) + ChatGPT external styles (oil painting, watercolor, vector, anime, print).<br> Auto-crops for 40+ social media platforms. Built for AI agents. </p> <p align="center"> <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-compatible-blue" alt="MCP"></a> <a href="https://www.apple.com/macos/"><img src="https://img.shields.io/badge/macOS-15.4%2B-black?logo=apple" alt="macOS"></a> <a href="https://python.org"><img src="https://img.shields.io/badge/Python-3.10%2B-3776AB?logo=python&logoColor=white" alt="Python"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License: MIT"></a> <a href="https://github.com/vakandi/apple-image-mcp/releases"><img src="https://img.shields.io/badge/version-1.1.0-orange" alt="Version"></a> </p> --- ## Why this exists Other Apple Intelligence MCP servers expose one tool: `generate_image`. That's it. **apple-image-mcp** gives your AI agent a full image pipeline: - **8 styles** — on-device (animation, illustration, sketch, emoji) + ChatGPT external (oil painting, watercolor, vector, anime, print) via Shortcuts.app - **17 tools** — generate, crop, batch, watermark, text overlay, filters, social packs - **40+ platform presets** — Instagram, TikTok, LinkedIn, YouTube, Pinterest, blog headers — all one prompt away - **Zero config** — runs locally on any Apple Silicon Mac with Apple Intelligence enabled --- ## Quick Start ### Option A — npx (recommended, zero setup) ```bash npx mcp-apple-image-playground ``` That's it. Python deps install automatically on first run. ### Option B — npm install ```bash npm install -g mcp-apple-image-playground mcp-apple-image-playground ``` ### Option C — From source ```bash pip install "mcp[cli]" pillow python3 apple_intelligence_community_manager.py ``` --- ## IDE Integration ### Cursor / Windsurf / VS Code Add to your MCP config (`.cursor/mcp.json` or Settings → MCP): ```json { "mcpServers": { "apple_image": { "command": "npx", "args": ["mcp-apple-image-playground"] } } } ``` > **Note:** If Cursor can't find npx, use the full path: > `"command": "/Users/YOU/.nvm/versions/node/v20.x.x/bin/npx"` ### Claude Desktop Add to `~/Library/Application Support/Claude/claude_desktop_config.json`: ```json { "mcpServers": { "apple_image": { "command": "npx", "args": ["mcp-apple-image-playground"] } } } ``` ### OpenCode Add to `~/.config/opencode/opencode.json` under `"mcp"`: ```json { "mcp": { "apple-image": { "type": "local", "command": ["npx", "mcp-apple-image-playground"], "enabled": true } } } ``` ### Claude Code / opencode CLI ```bash claude mcp add apple_image \ --scope user \ -- npx mcp-apple-image-playground ``` --- ## Available Tools ### Image Generation | Tool | Description | |------|-------------| | `generate_image` | Generate from text prompt via Shortcuts.app | | `generate_social_pack` | One prompt → multiple platform-sized crops (Instagram, Twitter, LinkedIn…) | | `generate_bundle` | Generate for a predefined bundle (e.g. `full_social`, `blog_set`) | | `generate_batch` | Generate multiple images from a list of prompts | ### Image Processing | Tool | Description | |------|-------------| | `add_text_overlay` | Add text with custom font, position, color, shadow | | `add_watermark` | Brand watermark with opacity control | | `create_gradient` | Generate gradient backgrounds (vertical, horizontal, diagonal) | | `create_text_post` | Ready-to-post text image (quote, announcement, tip) | | `apply_filter` | Blur, sharpen, brightness, contrast, sepia, noir | | `smart_crop` | Face-aware crop using Apple's Vision framework | | `crop_image` | Crop existing image to multiple platform sizes | | `resize_image` | Resize to exact dimensions or scale factor | ### Discovery | Tool | Description | |------|-------------| | `list_engines` | Check which engines are available | | `list_styles` | Show all available styles (on-device + ChatGPT external) | | `list_presets` | All 40+ platform presets with exact dimensions | | `list_bundles` | Predefined bundles (full_social, instagram_set, blog_set…) | --- ## Engine Details ### On-Device (Apple Intelligence) - **Styles**: `animation`, `illustration`, `sketch`, `emoji` - **Requires**: macOS 15.4+ with Apple Intelligence enabled, Apple Silicon Mac - **Privacy**: Runs entirely on your machine. No images leave your device. - **Speed**: ~5-10 seconds per image ### ChatGPT External Styles - **Styles**: `oil_painting`, `watercolor`, `vector`, `anime`, `print` - **Requires**: Internet connection, ChatGPT integrated into Siri - **How it works**: Routes through Siri's ChatGPT integration via Shortcuts.app - **Speed**: ~10-30 seconds per image (network dependent) --- ## Platform Presets One prompt → perfectly sized for every platform: ``` Instagram: post (1080×1080) · portrait (1080×1350) · story (1080×1920) · reel cover Twitter/X: post (1200×675) · header (1500×500) · card (1200×628) LinkedIn: post (1200×628) · article (744×400) · banner (1584×396) YouTube: thumbnail (1280×720) · channel art (2560×1440) · short (1080×1920) Pinterest: pin (1000×1500) · story (1080×1920) Blog: header (1200×630) · hero (1920×1080) · thumbnail (400×300) Facebook: post (1200×630) · cover (820×312) · story (1080×1920) TikTok: video cover (1080×1920) ``` Full list: call `list_platform_presets` on the running server. --- ## Example Agent Calls ### Generate a social media pack ```python generate_social_pack( prompt="a cozy coffee shop in autumn, warm colors", platforms=["instagram_post", "twitter_post", "linkedin_post"], style="illustration" ) # → 3 images, each cropped to the perfect platform size ``` ### Generate an oil painting ```python generate_image( prompt="a serene mountain landscape at golden hour", style="oil_painting" ) # → 1536×1536 oil painting via ChatGPT external style ``` ### Generate a bundle for your blog ```python generate_bundle( prompt="a rocket launching into a starry sky", bundle="blog_set", style="illustration" ) # → multiple images: blog_header, blog_inline, blog_thumbnail, og_image, square_thumbnail ``` ### Create a text post for social ```python create_text_post( text="50% OFF everything this weekend", width=1080, height=1080, bg_color="#1a1a2e", font_color="#FFFFFF", gradient=True ) # → ready-to-post text image with gradient background ``` ### Add text overlay to an image ```python add_text_overlay( image_path="/path/to/image.png", text="50% OFF", position="center", font_size=72, font_color="#FF0000", bg_color="#000000" ) ``` --- ## Requirements | Requirement | Details | |-------------|---------| | **macOS** | 15.4+ (Sequoia) or 26+ (Tahoe) | | **Hardware** | Apple Silicon Mac (M1, M2, M3, M4, M5) | | **Apple Intelligence** | Enabled in System Settings → Apple Intelligence & Siri | | **Image Playground** | Open once to download models (one-time, ~2GB) | | **Node.js** | 18+ (for npx) | | **Python** | 3.10+ (auto-installed with deps if missing) | --- ## Configuration ### Environment Variables | Variable | Default | Description | |----------|---------|-------------| | `APPLE_IMAGE_OUTPUT_DIR` | `~/Pictures/AI-Generated` | Where generated images are saved | | `APPLE_IMAGE_DEFAULT_STYLE` | `illustration` | Default style | --- ## Troubleshooting ### `ImagePlayground.ImageCreator.Error.creationFailed` This is a known macOS issue, especially on beta builds. Fixes: 1. Open **Image Playground.app** and generate one image manually 2. Confirm Apple Intelligence is enabled in System Settings 3. Ensure Image Playground models are fully downloaded ### Dock icon flashes during generation Expected behavior. Apple's `ImageCreator` requires the app to run in the foreground. The helper temporarily sets a Dock icon, generates, then exits. The icon disappears automatically. ### ChatGPT external styles timeout ChatGPT external styles (oil_painting, watercolor, vector, anime, print) require an active internet connection and ChatGPT integration. If they timeout, check your network and ensure Siri/ChatGPT is configured in System Settings. --- ## Architecture ``` ┌──────────────────┐ ┌──────────────────────────┐ ┌─────────────────┐ │ MCP Client │────▶│ npx launcher │────▶│ Python MCP │ │ (Claude, Cursor │◀────│ (Node.js, auto-deps) │◀────│ (FastMCP) │ │ OpenCode, etc.)│ │ │ │ │ └──────────────────┘ └──────────────────────────┘ ├─ Shortcuts.app │ │ (on-device) │ │ styles: │ │ animation, │ │ illustration, │ │ sketch, emoji │ │ │ ├─ ChatGPT │ │ (external) │ │ via Siri │ └─────────────────┘ ``` The Node.js launcher handles Python dependency management and Swift compilation automatically. The Python server exposes 17 MCP tools via stdio transport. All image generation goes through Shortcuts.app's GenerateImageIntent — on-device styles use Apple's Image Playground directly, external styles route through Siri's ChatGPT integration. --- ## Project Structure ``` apple-image-mcp/ ├── bin/ │ └── mcp-apple-image-playground # Node.js launcher (npx entry point) ├── apple_intelligence/ # Python package │ ├── __init__.py │ ├── server.py # 16 MCP tool definitions │ ├── engines.py # Shortcuts.app engine │ ├── processing.py # PIL crop, resize, font utilities │ ├── platforms.py # 40+ platform presets & bundles │ └── response.py # Structured response helpers ├── apple_intelligence_community_manager.py # Python MCP server entry point ├── imagegen_helper.swift # Swift binary source ├── postinstall.js # Auto-setup on npm install ├── package.json ├── README.md └── LICENSE ``` --- ## Contributing Contributions welcome. Please open an issue first to discuss what you'd like to change. --- ## License MIT License. See [LICENSE](LICENSE) for details. --- ## Acknowledgments - [Apple ImagePlayground API](https://developer.apple.com/documentation/imageplayground) — the on-device image generation framework - [FastMCP](https://github.com/jlowin/fastmcp) — the MCP server framework - [Pillow](https://python-pillow.org) — image processing