# OpenRouter Image MCP Server 🖼️

> **🤖 A Model Context Protocol (MCP) server** for generating and editing images using OpenRouter's API with Gemini 2.5 Flash Image model.

一个用于通过 OpenRouter API 生成和编辑图像的 Model Context Protocol (MCP) 服务器，支持自定义图像尺寸比例。

## ✨ 特性

- 🎨 **生成图像**: 从文本描述创建全新的图像
- ✏️ **编辑图像**: 使用文本提示修改现有图像
- 🔄 **迭代编辑**: 持续编辑上次生成/编辑的图像
- 📐 **自定义尺寸**: 支持多种图像宽高比（1:1, 16:9, 9:16, 等）
- 🖼️ **多参考图像**: 使用参考图像进行风格迁移和引导
- 🌍 **跨平台**: 支持 Windows、macOS 和 Linux 的智能文件路径
- 🔧 **简单配置**: 使用 API 密钥轻松配置
- 📁 **自动文件管理**: 自动保存图像并组织命名

## 🔑 获取 API 密钥

1. 访问 [OpenRouter Settings - Keys](https://openrouter.ai/settings/keys)
2. 创建一个新的 API 密钥
3. 复制密钥用于配置

## 💻 使用方法

### 在 Claude Desktop 中使用

#### 配置方法：

在 Claude Desktop 的 MCP 配置中添加：

**方法 A：使用环境变量（推荐 - 最安全）**
```json
{
  "mcpServers": {
    "openrouter-image": {
      "command": "npx",
      "args": ["openrouter-image-mcp"],
      "env": {
        "OPENROUTER_API_KEY": "your-openrouter-api-key-here"
      }
    }
  }
}
```

**方法 B：不使用环境变量**
```json
{
  "mcpServers": {
    "openrouter-image": {
      "command": "npx",
      "args": ["openrouter-image-mcp"]
    }
  }
}
```

#### 使用示例：
```
生成一张日落山景图像
```

```
将这张图像编辑成添加一些飞鸟
```

```
继续编辑，让它更加戏剧化
```

```
生成一张 16:9 比例的未来城市图像
```

## 🎯 在 Cursor 中使用

### 配置方法：

在 Cursor 的 MCP 配置中添加：

**方法 A：使用环境变量（推荐）**
```json
{
  "openrouter-image": {
    "command": "node",
    "args": ["E:\\Study\\赚钱\\工具\\Openrouter-Image-MCP\\dist\\index.js"],
    "env": {
      "OPENROUTER_API_KEY": "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"
    }
  }
}
```

**方法 B：不使用环境变量**
```json
{
  "openrouter-image": {
    "command": "npx",
    "args": ["openrouter-image-mcp"]
  }
}
```

### 使用示例：
- 让 Cursor 为你的应用生成图像
- 创建模型和原型
- 为项目生成资源

## 🔧 在其他 MCP 客户端中使用

如果你使用其他 MCP 客户端，可以使用以下任一配置方法：

### 配置方法

**方法 A：MCP 配置中的环境变量（推荐）**
```json
{
  "openrouter-image": {
    "command": "npx",
    "args": ["openrouter-image-mcp"],
    "env": {
      "OPENROUTER_API_KEY": "your-openrouter-api-key-here"
    }
  }
}
```

**方法 B：系统环境变量**
```bash
export OPENROUTER_API_KEY="your-openrouter-api-key-here"
npx openrouter-image-mcp
```

**方法 C：使用配置工具**
```bash
npx openrouter-image-mcp
# 服务器会在首次使用时提示你配置
# 这会在当前目录创建 .openrouter-image-config.json 文件
```

## 🛠️ 可用命令

### `generate_image`
从文本提示创建新图像。
```typescript
generate_image({
  prompt: "A futuristic city at night with neon lights",
  aspectRatio: "16:9" // 可选
})
```

**支持的宽高比：**
- `1:1` → 1024×1024（默认）
- `16:9` → 1344×768
- `9:16` → 768×1344
- `3:4` → 864×1184
- `4:3` → 1184×864
- `2:3` → 832×1248
- `3:2` → 1248×832
- `4:5` → 896×1152
- `5:4` → 1152×896
- `21:9` → 1536×672

### `edit_image`
编辑特定的图像文件。
```typescript
edit_image({
  imagePath: "/path/to/image.png",
  prompt: "Add a rainbow in the sky",
  referenceImages: ["/path/to/reference.jpg"], // 可选
  aspectRatio: "16:9" // 可选
})
```

### `continue_editing`
继续编辑上次生成/编辑的图像。
```typescript
continue_editing({
  prompt: "Make it more colorful",
  referenceImages: ["/path/to/style.jpg"], // 可选
  aspectRatio: "1:1" // 可选
})
```

### `get_last_image_info`
获取上次生成的图像信息。
```typescript
get_last_image_info()
```

### `configure_openrouter_token`
配置你的 OpenRouter API 密钥。
```typescript
configure_openrouter_token({
  apiKey: "your-openrouter-api-key"
})
```

### `get_configuration_status`
检查 API 密钥是否已配置。
```typescript
get_configuration_status()
```

## ⚙️ 配置优先级

MCP 服务器按以下优先级顺序加载你的 API 密钥：

1. **🥇 MCP 配置环境变量**（最高优先级）
   - 在 MCP 客户端配置中设置
   - 最安全，因为包含在 MCP 配置中
   - 示例：`"env": { "OPENROUTER_API_KEY": "your-key" }`

2. **🥈 系统环境变量**
   - 在 shell/系统环境中设置
   - 示例：`export OPENROUTER_API_KEY="your-key"`

3. **🥉 本地配置文件**（最低优先级）
   - 使用 `configure_openrouter_token` 工具时创建
   - 作为 `.openrouter-image-config.json` 存储在当前目录
   - 自动被 Git 和 NPM 忽略

**💡 推荐**: 使用方法 1（MCP 配置环境变量）以获得最佳安全性和便利性。

## 📁 文件存储

图像自动保存到适合平台的位置：

- **Windows**: `%USERPROFILE%\\Documents\\openrouter-images\\`
- **macOS/Linux**: `./generated_imgs/`（在当前目录）
- **系统目录**: `~/openrouter-images/`（从系统路径运行时）

文件命名规范：
- 生成的图像：`generated-[timestamp]-[id].png`
- 编辑的图像：`edited-[timestamp]-[id].png`

## 🎨 示例工作流程

### 基本图像生成
1. `generate_image` - 创建你的基础图像
2. `continue_editing` - 优化和改进
3. `continue_editing` - 添加最后的润色

### 风格迁移
1. `generate_image` - 创建基础内容
2. `edit_image` - 使用参考图像应用风格
3. `continue_editing` - 微调结果

### 迭代设计
1. `generate_image` - 从概念开始
2. `get_last_image_info` - 检查当前状态
3. `continue_editing` - 进行调整
4. 重复直到满意

### 自定义尺寸
1. `generate_image` - 使用 aspectRatio: "16:9" 创建宽屏图像
2. `continue_editing` - 使用 aspectRatio: "9:16" 调整为竖屏
3. `edit_image` - 使用不同比例创建变体

## 🔧 开发

### 本地开发

```bash
# 克隆仓库
git clone https://github.com/yourusername/openrouter-image-mcp.git
cd openrouter-image-mcp

# 安装依赖
npm install

# 开发模式运行
npm run dev

# 生产构建
npm run build

# 运行测试
npm test
```

### 技术栈

- **TypeScript** - 类型安全开发
- **Node.js** - 运行时环境  
- **Zod** - 模式验证
- **OpenAI SDK** - OpenRouter API 客户端
- **MCP SDK** - Model Context Protocol

## 📋 要求

- Node.js 18.0.0 或更高版本
- 来自 OpenRouter 的 API 密钥
- 兼容 Claude Desktop、Cursor 和其他 MCP 客户端

## 🤝 贡献

欢迎贡献！请随时：

- 报告 bug
- 建议新功能
- 提交 pull request
- 改进文档

## 📄 许可证

MIT 许可证 - 详见 [LICENSE](LICENSE) 文件。

## 🙏 致谢

- **[OpenRouter](https://openrouter.ai/)** - 提供强大的 API 平台
- **[Google AI](https://ai.google.dev/)** - Gemini 2.5 Flash Image 模型
- **[Anthropic](https://www.anthropic.com/)** - Model Context Protocol
- **[Claude Code](https://claude.ai/code)** - 用于生成此项目
- **开源社区** - 提供精彩的工具和库

## 📞 支持

- 🐛 **问题**: [GitHub Issues](https://github.com/yourusername/openrouter-image-mcp/issues)
- 📖 **文档**: 本 README 和内联代码注释
- 💬 **讨论**: [GitHub Discussions](https://github.com/yourusername/openrouter-image-mcp/discussions)

## 🔗 链接

- [OpenRouter 文档](https://openrouter.ai/docs)
- [OpenRouter 图像生成指南](https://openrouter.ai/docs/features/multimodal/image-generation)
- [MCP 协议规范](https://modelcontextprotocol.io/)
- [Gemini API 文档](https://ai.google.dev/gemini-api/docs)

---

*✨ 通过 OpenRouter 和 MCP 协议实现强大的 AI 图像生成功能！*