内容
# image-mcp-worker
MCP（模型上下文协议）兼容的图像生成工作器，在Cloudflare Workers上运行。从文本提示生成图像，并提供直接下载URL和base64支持。
## 功能
- **MCP 协议** — 流式HTTP / JSON-RPC 2.0，与任何MCP客户端兼容
- **自带提供商** — 通过标头或环境变量传递任何OpenAI兼容的图像API
- **直接下载URL** — 生成的图像作为原始PNG通过`/img/{id}.png`提供
- **Base64 JSON** — 也可通过`/img/{id}.png?format=b64`获取
- **Cloudflare KV存储** — 图像缓存1小时，自动过期
- **多租户准备** — 每个请求的标头覆盖API密钥、基础URL和模型
## 快速开始
### 部署到Cloudflare Workers
1. Fork此仓库
2. 创建一个KV命名空间：
```bash
wrangler kv namespace create IMAGE_KV
```
3. 设置您的密钥：
```bash
wrangler secret put API_KEY
wrangler secret put API_BASE_URL # 例如：https://your-provider.com/v1
wrangler secret put MODEL # 可选，默认值：gpt-image-1
```
4. 部署：
```bash
wrangler deploy
```
### 配置
所有配置都可以通过**环境变量**（部署级别）或**请求标头**（每个请求覆盖）设置：
| 环境变量 | 标头 | 必需 | 默认值 | 描述 |
|---|---|---|---|---|
| `API_KEY` | `X-API-Key` | ✅ | — | 您的图像提供商的API密钥 |
| `API_BASE_URL` | `X-API-Base-URL` | ✅ | — | 提供商基础URL（例如`https://api.example.com/v1`） |
| `MODEL` | `X-Model` | ❌ | `gpt-image-1` | 模型名称 |
**优先级：标头 > 环境变量 > 默认值**
这意味着您可以部署带有环境变量以供自己使用，还允许其他用户通过标头传递自己的凭证。
## API 端点
### `POST /mcp` — MCP 协议
标准MCP流式HTTP端点。支持`initialize`、`tools/list`、`tools/call`、`ping`。
**工具：`generate_image`**
```json
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "generate_image",
"arguments": {
"prompt": "一只武士猫在霓虹灯照亮的赛博朋克城市",
"size": "1024x1024"
}
}
}
```
响应包括下载URL和内联base64：
```json
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{
"type": "text",
"text": "✅ 图片生成（1024x1024，gpt-image-1）\n\n下载URL：https://your-worker.example.com/img/abc123.png\n\n直接链接有效期为1小时。\nBase64 JSON：https://your-worker.example.com/img/abc123.png?format=b64"
},
{
"type": "image",
"data": "iVBORw0KGgo...",
"mimeType": "image/png"
}
]
}
}
```
**带有每个请求标头（多租户）：**
```bash
curl -X POST https://your-worker.example.com/mcp \
-H "Content-Type: application/json" \
-H "X-API-Key: sk-your-key" \
-H "X-API-Base-URL: https://your-provider.com/v1" \
-H "X-Model: dall-e-3" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"generate_image","arguments":{"prompt":"日落于山脉之上"}}}'
```
### `GET /img/{id}.png` — 直接PNG下载
返回原始PNG二进制数据。生成后有效期为1小时。
```bash
curl -o image.png https://your-worker.example.com/img/abc123.png
```
### `GET /img/{id}.png?format=b64` — Base64 JSON
返回base64编码的图像作为JSON：
```json
{
"id": "abc123",
"mime_type": "image/png",
"data": "iVBORw0KGgo..."
}
```
### `POST /tools/generate_image` — REST 端点（旧版）
用于简单集成的非MCP REST接口：
```bash
curl -X POST https://your-worker.example.com/tools/generate_image \
-H "Content-Type: application/json" \
-H "X-API-Key: sk-your-key" \
-H "X-API-Base-URL: https://your-provider.com/v1" \
-d '{"prompt":"一只红色熊猫吃竹笋","size":"1024x1024"}'
```
### `GET /health` — 健康检查
```json
{
"ok": true,
"name": "image-mcp-worker",
"version": "3.0.0",
"tools": ["generate_image"],
"protocol": "MCP Streamable HTTP",
"endpoints": { ... }
}
```
## 连接到MCP客户端
### Claude Desktop / Claude Code
添加到您的MCP客户端配置：
```json
{
"mcpServers": {
"image-gen": {
"url": "https://your-worker.example.com/mcp",
"headers": {
"X-API-Key": "sk-your-key",
"X-API-Base-URL": "https://your-provider.com/v1"
}
}
}
}
```
### Hermes Agent
```bash
hermes mcp add image-gen --transport http --url https://your-worker.example.com/mcp \
--header "X-API-Key: sk-your-key" \
--header "X-API-Base-URL: https://your-provider.com/v1"
```
## 支持的尺寸
| 尺寸 | 宽高比 |
|---|---|
| `1024x1024` | 1:1（默认） |
| `1024x1536` | 2:3（肖像） |
| `1536x1024` | 3:2（风景） |
| `auto` | 提供商决定 |
## Cloudflare KV免费层限制
| 资源 | 免费限制 |
|---|---|
| 读取 | 100,000 / 天 |
| **写入** | **1,000 / 天**（限制每天图像生成） |
| 存储 | 1 GB |
| 列表操作 | 1,000 / 天 |
图像通过TTL自动过期1小时，因此存储是自我清理的。
## 许可证
该项目根据GNU通用公共许可证v3.0许可 — 请参阅[LICENSE](LICENSE)文件了解详细信息。
