内容
<p align="center">
<img src="assets/banners/banner.png" alt="Apple Image MCP — 本地 AI 图片生成，适用于 macOS" width="100%">
</p>
<p align="center">
<strong>通过 Image Playground 实现 macOS 图片 AI 生成。17 种工具，零 API 密钥。</strong><br>
本地样式（动画、插图、素描）+ ChatGPT 外部样式（油画、水彩、矢量、动漫、印刷）。<br>
自动裁剪适用于 40 多个社交媒体平台。为 AI 代理而构建。
</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>
---
## 为什么存在
其他 Apple Intelligence MCP 服务器只开放一个工具：`generate_image`。
**apple-image-mcp** 为您的 AI 代理提供完整的图片处理流程：
- **8 种样式** — 本地（动画、插图、素描、表情符号）+ ChatGPT 外部（油画、水彩、矢量、动漫、印刷）通过 Shortcuts.app
- **17 种工具** — 生成、裁剪、批量处理、水印、文本叠加、过滤器、社交媒体包
- **40 多个平台预设** — Instagram、TikTok、LinkedIn、YouTube、Pinterest、博客标题 — 所有操作只需一个提示
- **零配置** — 在任何启用 Apple Intelligence 的 Apple Silicon Mac 上本地运行
---
## 快速开始
### 选项 A — npx（推荐，零配置）
```bash
npx mcp-apple-image-playground
```
就这样。Python 依赖项会在首次运行时自动安装。
### 选项 B — npm 安装
```bash
npm install -g mcp-apple-image-playground
mcp-apple-image-playground
```
### 选项 C — 从源码
```bash
pip install "mcp[cli]" pillow
python3 apple_intelligence_community_manager.py
```
---
## IDE 集成
### Cursor / Windsurf / VS Code
将以下内容添加到您的 MCP 配置（`.cursor/mcp.json` 或 设置 → MCP）：
```json
{
"mcpServers": {
"apple_image": {
"command": "npx",
"args": ["mcp-apple-image-playground"]
}
}
}
```
> **注意：** 如果 Cursor 找不到 npx，请使用完整路径：
> `"command": "/Users/YOU/.nvm/versions/node/v20.x.x/bin/npx"`
### Claude Desktop
将以下内容添加到 `~/Library/Application Support/Claude/claude_desktop_config.json`：
```json
{
"mcpServers": {
"apple_image": {
"command": "npx",
"args": ["mcp-apple-image-playground"]
}
}
}
```
### OpenCode
将以下内容添加到 `~/.config/opencode/opencode.json` 下的 `"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
```
---
## 可用工具
### 图片生成
| 工具 | 描述 |
|------|-------------|
| `generate_image` | 通过 Shortcuts.app 从文本提示生成 |
| `generate_social_pack` | 一个提示 → 多个平台尺寸裁剪（Instagram、Twitter、LinkedIn…） |
| `generate_bundle` | 为预定义的包生成（例如 `full_social`、`blog_set`） |
| `generate_batch` | 从提示列表生成多个图片 |
### 图片处理
| 工具 | 描述 |
|------|-------------|
| `add_text_overlay` | 添加文本，自定义字体、位置、颜色、阴影 |
| `add_watermark` | 品牌水印，透明度控制 |
| `create_gradient` | 生成渐变背景（垂直、水平、对角） |
| `create_text_post` | 准备发布的文本图片（引用、公告、提示） |
| `apply_filter` | 模糊、锐化、亮度、对比度、棕色、黑色 |
| `smart_crop` | 使用 Apple 的 Vision 框架进行人脸感知裁剪 |
| `crop_image` | 将现有图片裁剪为多个平台尺寸 |
| `resize_image` | 调整为精确尺寸或缩放因子 |
### 发现
| 工具 | 描述 |
|------|-------------|
| `list_engines` | 检查哪些引擎可用 |
| `list_styles` | 显示所有可用样式（本地 + ChatGPT 外部） |
| `list_presets` | 所有 40 多个平台预设，精确尺寸 |
| `list_bundles` | 预定义包（full_social、instagram_set、blog_set…） |
---
## 引擎详情
### 本地（Apple Intelligence）
- **样式**：`animation`、`illustration`、`sketch`、`emoji`
- **要求**：macOS 15.4+，启用 Apple Intelligence，Apple Silicon Mac
- **隐私**：完全在您的机器上运行。没有图片会离开您的设备。
- **速度**：每张图片约 5-10 秒
### ChatGPT 外部样式
- **样式**：`oil_painting`、`watercolor`、`vector`、`anime`、`print`
- **要求**：互联网连接，ChatGPT 集成到 Siri
- **工作原理**：通过 Shortcuts.app 路由到 Siri 的 ChatGPT 集成
- **速度**：每张图片约 10-30 秒（依赖网络）
---
## 平台预设
一个提示 → 为每个平台完美尺寸：
```
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)
```
完整列表：调用 `list_platform_presets` 在运行的服务器上。
---
## 示例代理调用
### 生成社交媒体包
```python
generate_social_pack(
prompt="一个温暖的秋天咖啡店，温暖的颜色",
platforms=["instagram_post", "twitter_post", "linkedin_post"],
style="illustration"
)
# → 3 张图片，每张都裁剪为完美的平台尺寸
```
### 生成油画
```python
generate_image(
prompt="一个宁静的山景，在金色时段",
style="oil_painting"
)
# → 1536×1536 油画，通过 ChatGPT 外部样式
```
### 为博客生成包
```python
generate_bundle(
prompt="一枚火箭发射到星空",
bundle="blog_set",
style="illustration"
)
# → 多张图片：blog_header、blog_inline、blog_thumbnail、og_image、square_thumbnail
```
### 为社交媒体创建文本帖
```python
create_text_post(
text="本周末所有商品 50% 折扣",
width=1080,
height=1080,
bg_color="#1a1a2e",
font_color="#FFFFFF",
gradient=True
)
# → 准备发布的文本图片，带有渐变背景
```
### 在图片上添加文本叠加
```python
add_text_overlay(
image_path="/path/to/image.png",
text="50% 折扣",
position="center",
font_size=72,
font_color="#FF0000",
bg_color="#000000"
)
```
---
## 要求
| 要求 | 详情 |
|-------------|---------|
| **macOS** | 15.4+（Sequoia）或 26+（Tahoe） |
| **硬件** | Apple Silicon Mac（M1、M2、M3、M4、M5） |
| **Apple Intelligence** | 在系统设置中启用 → Apple Intelligence & Siri |
| **Image Playground** | 打开一次以下载模型（一次性，约 2GB） |
| **Node.js** | 18+（用于 npx） |
| **Python** | 3.10+（如果缺少，自动安装依赖） |
---
## 配置
### 环境变量
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `APPLE_IMAGE_OUTPUT_DIR` | `~/Pictures/AI-Generated` | 生成的图片保存位置 |
| `APPLE_IMAGE_DEFAULT_STYLE` | `illustration` | 默认样式 |
---
## 故障排除
### `ImagePlayground.ImageCreator.Error.creationFailed`
这是一个已知的 macOS 问题，尤其是在测试版构建中。解决方法：
1. 打开 **Image Playground.app** 并手动生成一个图片
2. 确认 Apple Intelligence 在系统设置中启用
3. 确保 Image Playground 模型已完全下载
### Dock 图标在生成期间闪烁
预期行为。Apple 的 `ImageCreator` 需要应用程序在前台运行。辅助程序暂时设置 Dock 图标，生成后退出。图标会自动消失。
### ChatGPT 外部样式超时
ChatGPT 外部样式（油画、水彩、矢量、动漫、印刷）需要活跃的互联网连接和 ChatGPT 集成。如果它们超时，请检查您的网络并确保 Siri/ChatGPT 在系统设置中配置。
---
## 架构
```
┌──────────────────┐ ┌──────────────────────────┐ ┌─────────────────┐
│ MCP 客户端 │────▶│ npx 启动器 │────▶│ Python MCP │
│ （Claude、Cursor │◀────│ （Node.js，自动依赖） │◀────│ （FastMCP） │
│ OpenCode 等）│ │ │ │ │
└──────────────────┘ └──────────────────────────┘ ├─ Shortcuts.app │
│ （本地） │
│ 样式： │
│ 动画、 │
│ 插图、 │
│ 素描、表情符号 │
│ │
├─ ChatGPT │
│ （外部） │
│ 通过 Siri │
└─────────────────┘
```
Node.js 启动器自动处理 Python 依赖管理和 Swift 编译。Python 服务器通过 stdio 传输暴露 17 个 MCP 工具。所有图片生成都通过 Shortcuts.app 的 GenerateImageIntent — 本地样式直接使用 Apple 的 Image Playground，外部样式通过 Siri 的 ChatGPT 集成路由。
---
## 项目结构
```
apple-image-mcp/
├── bin/
│ └── mcp-apple-image-playground # Node.js 启动器（npx 入口点）
├── apple_intelligence/ # Python 包
│ ├── __init__.py
│ ├── server.py # 16 个 MCP 工具定义
│ ├── engines.py # Shortcuts.app 引擎
│ ├── processing.py # PIL 裁剪、调整大小、字体实用程序
│ ├── platforms.py # 40 多个平台预设和包
│ └── response.py # 结构化响应帮助程序
├── apple_intelligence_community_manager.py # Python MCP 服务器入口点
├── imagegen_helper.swift # Swift 二进制源代码
├── postinstall.js # npm 安装时的自动设置
├── package.json
├── README.md
└── LICENSE
```
---
## 贡献
欢迎贡献。请先打开一个问题，讨论您要更改的内容。
---
## 许可证
MIT 许可证。有关详细信息，请参见 [LICENSE](LICENSE)。
---
## 致谢
- [Apple ImagePlayground API](https://developer.apple.com/documentation/imageplayground) — 本地图片生成框架
- [FastMCP](https://github.com/jlowin/fastmcp) — MCP 服务器框架
- [Pillow](https://python-pillow.org) — 图片处理
