内容
# Pixara MCP 服务器
<p align="center">
<img src="./logo.png" alt="Logo" width="300" />
</p>
一个 MCP 服务器，为 LLMs 提供直接访问 OpenRouter 的图像 API 的能力，以生成图像，编辑/转换现有图像，并浏览模型目录，所有操作都通过 4 个工具完成。
我创建了这个项目，因为我看到 OpenRouter 发布了一个新的图像 API（`/api/v1/images`），该 API 提供了一个端点，可用于图像生成和图像编辑模型，如 GPT Image、Nano Banana、Flux、Recraft 等。 使用 `pixara_list_image_models` 工具查看 OpenRouter 当前的完整模型列表。
## 功能
- **生成图像**：根据文本提示，使用任意 OpenRouter 图像模型生成图像
- **编辑/转换图像**（img2img）：使用本地文件、URL 或原始 base64 作为参考，工具会为您读取和编码本地文件
- **列出模型**：按提供商、名称和功能（img2img、流媒体、透明背景）进行筛选，并支持分页
- **查看模型的端点详情**：按提供商定价、支持的参数和允许的直通选项 - 在您调用不支持的服务之前
- 生成的图像会被解码并保存到磁盘，因此响应保持较小，并返回文件路径
- 针对常见故障模式提供清晰的错误消息：参数错误/冲突、无效密钥、积分不足、速率限制、提供商不可用
## 快速入门（推荐）
Pixara 已在 npm 上发布为 [`@pinkpixel/pixara-mcp`](https://www.npmjs.com/package/@pinkpixel/pixara-mcp)。
使用它最简单的方法是通过 `npx` - 无需安装、无需克隆、无需构建步骤。
在您的 MCP 配置文件（`claude_desktop_config.json`）或 MCP 客户端的 `.json` 配置文件中添加以下内容：
```json
{
"mcpServers": {
"pixara": {
"command": "npx",
"args": ["-y", "@pinkpixel/pixara-mcp"],
"env": {
"OPENROUTER_API_KEY": "sk-or-v1-your-key-here",
"OPENROUTER_IMAGE_OUTPUT_DIR": "/absolute/path/to/wherever/you/want/images"
}
}
}
}
```
重启客户端，您应该会看到四个 `pixara_*` 工具可用。`npx -y` 会在首次运行时获取并缓存软件包，因此无需手动更新。新版本将自动获取。
## 配置
| 变量 | 必需 | 描述 |
|---|---|---|
| `OPENROUTER_API_KEY` | 是 | 在 [openrouter.ai/keys](https://openrouter.ai/keys) 获取 |
| `OPENROUTER_IMAGE_OUTPUT_DIR` | 否 | 生成的图像保存位置。默认为 `./pixara-images` |
服务器只需从 `process.env` 读取这些变量 - 没有内置的 `.env` 文件加载。无论您是通过 `npx` 还是从源代码运行，请在 MCP 配置的 `env` 块中设置这些变量，如上所示。`OPENROUTER_IMAGE_OUTPUT_DIR` 是可选的 - 如果您不设置，图像将保存到 `./pixara-images`，相对于服务器进程运行的位置；如果您想要一个可预测的位置，请设置为绝对路径。
## 从源代码安装
适用于本地开发，或如果您不想依赖 `npx`：
需要 Node.js 18+。
```bash
git clone https://github.com/sizzlebop/pixara-mcp.git
cd pixara-mcp
npm install
npm run build
```
然后，将您的 MCP 配置文件指向已构建的文件，而不是 `npx`:
```json
{
"mcpServers": {
"pixara": {
"command": "node",
"args": ["/absolute/path/to/openrouter-image-mcp/dist/index.js"],
"env": {
"OPENROUTER_API_KEY": "sk-or-v1-your-key-here",
"OPENROUTER_IMAGE_OUTPUT_DIR": "/absolute/path/to/wherever/you/want/images"
}
}
}
}
```
## 工具
### `pixara_generate_image`
文本转图像。必填：`model`、`prompt`。可选：`n`、`resolution`、`aspect_ratio`、`size`、`quality`、`output_format`、`background`、`output_compression`、`seed`、`provider_options`、`output_dir`、`filename_prefix`。
不要将 `size` 与 `resolution`/`aspect_ratio` 结合使用 - 选择其中一个，工具将拒绝调用并显示清晰的消息，如果您混用它们。
### `pixara_edit_image`
与 `generate_image` 相同的参数，加上一个必填的 `input_references` 数组。每个条目是：
```json
{ "source": "file", "path": "/path/to/photo.png" }
{ "source": "url", "url": "https://example.com/photo.jpg" }
{ "source": "base64", "data": "<base64>", "media_type": "image/png" }
```
### `pixara_list_image_models`
只读，免费（无图像计费）。按 `filter`（子字符串）、`provider` 或功能布尔值（`supports_img2img`、`supports_streaming`、`supports_transparent_background`）筛选。分页使用 `limit`/`offset`。
### `pixara_get_model_details`
只读，免费。传递一个 `model` 斜杠，获取每个提供商的定价以及提供商支持的参数/直通选项。在使用 `provider_options` 之前调用此接口很有用，因为不支持的参数将被静默丢弃或被 API 拒绝。
## 如何决定图像保存位置
每次生成/编辑调用都会解码 OpenRouter 返回的 base64 图像（s）并将其写入 `OPENROUTER_IMAGE_OUTPUT_DIR`（或每个调用的 `output_dir` 覆盖），命名为 `{prefix}-{timestamp}-{index}.{ext}`。扩展名遵循 `output_format`，除了矢量输出（Recraft 的 SVG 模型），它通过响应 `media_type` 检测并写入 `.svg`。
## 限制
- 暂无 SSE 流媒体支持（参见路线图）
- 模型功能因提供商而异，OpenRouter 目录更新迅速 - 始终信任 `pixara_list_image_models`/`pixara_get_model_details` 而不是任何硬编码列表
- 这是新功能 - OpenRouter 的图像 API 仅发布几周，因此预计模型 ID 和参数会随时间推移而变化
## 许可证
Apache 2.0 - 请参阅 [LICENSE](LICENSE)。
---
由 [Pink Pixel](https://pinkpixel.dev) 用 💖 制作
