README.md•8.1 kB
# 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 图像生成功能！*