内容
# img-mcp
[](https://www.npmjs.com/package/img-mcp)
[](https://github.com/aboubak-art/img-mcp/actions/workflows/ci.yml)
[](./LICENSE)
📚 **[查看网站](https://aboubak-art.github.io/img-mcp/)**
一个开源的 [模型上下文协议（MCP）](https://modelcontextprotocol.io) 服务器，允许 AI 代理生成图像。目前支持谷歌的 **Nano Banana** 图像生成模型（Gemini Flash Image）通过 Gemini API。
## 功能
- **文本到图像生成** 通过 MCP 工具
- **图像到图像 / 参考图像生成** 通过传递 base64 图像或数据 URI
- **透明背景生成** 使用 `@imgly/background-removal-node`
- **谷歌 Nano Banana** 支持（`gemini-3.1-flash-image`，`gemini-3.1-flash-lite-image`，`gemini-3-pro-image`等）
- **用户提供的 API 密钥** — 您可以使用自己的谷歌 API 密钥
- **零安装使用** 使用 `npx img-mcp`
- **多种纵横比和图像尺寸**
## 安装
### 通过 `npx`（推荐）
```bash
npx -y img-mcp
```
### 通过 npm
```bash
npm install -g img-mcp
img-mcp
```
## 配置
将您的谷歌 API 密钥设置为环境变量：
```bash
export GOOGLE_API_KEY="您的谷歌API密钥"
```
您可以从 [谷歌 AI Studio](https://aistudio.google.com/app/apikey) 获取 API 密钥。
### 图像尺寸
支持的 `image_size` 值为 `512`、`1K`、`2K` 和 `4K`。请注意，`2K` 和 `4K` 需要支持高分辨率输出的 Nano Banana 模型，例如 `gemini-3-pro-image`。默认的 `gemini-3.1-flash-image` 模型通常支持 `512` 和 `1K`。
### 可选环境变量
| 变量 | 描述 | 默认值 |
| --- | --- | --- |
| `GOOGLE_API_KEY` | 您的谷歌 Gemini API 密钥 | — |
| `GOOGLE_IMAGE_MODEL` | 默认 Nano Banana 模型 ID | `gemini-3.1-flash-image` |
### 可选：透明背景支持
`transparent_background` 功能依赖于 `@imgly/background-removal-node`，该依赖项遵循 **AGPL-3.0** 许可。为了保持 `img-mcp` 自身遵循宽容的 MIT 许可，此依赖项是**可选的**，默认情况下不会安装。
要启用透明背景，请在您的环境中安装同级依赖项：
```bash
npm install -g @imgly/background-removal-node
```
或者，在使用 `npx` 时，请在本地项目中将其与 `img-mcp` 一起安装。如果在缺少该软件包的情况下请求 `transparent_background`，则该工具将返回错误并提供安装说明。
## 与 MCP 主机一起使用
将服务器添加到您的 MCP 主机配置中（例如，Claude Desktop、Cursor 或 Windsurf）：
```json
{
"mcpServers": {
"img-mcp": {
"command": "npx",
"args": ["-y", "img-mcp"],
"env": {
"GOOGLE_API_KEY": "您的谷歌API密钥"
}
}
}
}
```
## 可用工具
### `generate_image`
根据文本提示生成图像。
**参数**
| 参数 | 类型 | 必需 | 默认值 | 描述 |
| --- | --- | --- | --- | --- |
| `prompt` | `string` | 是 | — | 图像的文本描述 |
| `model` | `string` | 否 | `gemini-3.1-flash-image` | Nano Banana 模型 ID |
| `n` | `number` | 否 | `1` | 要生成的图像数量（1-4） |
| `aspect_ratio` | `string` | 否 | `1:1` | 宽高比（`1:1`、`16:9`、`9:16`、`3:2`、`2:3`、`4:3`、`3:4`、`4:5`、`5:4`、`21:9`） |
| `image_size` | `string` | 否 | `1K` | 图像尺寸（`512`、`1K`、`2K`、`4K`）。较大的尺寸可能需要诸如 `gemini-3-pro-image` 之类的模型。 |
| `output_path` | `string` | 否 | — | 如果提供，则将生成的图像保存到磁盘上的此路径，并返回文件路径而不是 base64 |
| `images` | `string` 或 `string[]` | 否 | — | 一个或多个参考图像作为 base64 字符串或数据 URI（`data:image/png;base64,...`） |
| `transparent_background` | `boolean` | 否 | `false` | 当 `true` 时，提示将被重写为请求亮绿色背景，生成后将删除背景；输出始终为 PNG |
**示例**
```json
{
"prompt": "日落时的未来城市，带有飞行汽车",
"aspect_ratio": "16:9",
"image_size": "2K",
"n": 1
}
```
**带有参考图像的示例**
```json
{
"prompt": "以参考照片的风格生成肖像",
"aspect_ratio": "1:1",
"image_size": "1K",
"images": [
"data:image/png;base64,iVBORw0KGgo..."
]
}
```
**带有透明背景的示例**
```json
{
"prompt": "戴墨镜的金毛猎犬",
"aspect_ratio": "1:1",
"image_size": "1K",
"transparent_background": true,
"output_path": "/tmp/dog.png"
}
```
**输出行为**
- 如果提供了 `output_path`，则生成的图像将写入磁盘，工具将返回保存的文件路径。当 `n` 大于 1 时，附加图像将保存为带有编号后缀的文件（例如 `image_1.png`、`image_2.png`）。
- 如果省略 `output_path`，则生成的图像将作为 base64 内容返回。
- 当 `transparent_background` 为 `true` 时，输出始终为带有透明度的 PNG，`output_path` 将被重写为使用 `.png` 扩展名。
## 开发
```bash
# 安装依赖项
npm install
# 以开发模式运行
npm run dev
# 构建
npm run build
# 检查 / 类型检查
npm run lint
```
### 使用 MCP 检查器进行测试
```bash
npm run build
npx @modelcontextprotocol/inspector dist/index.js
```
## 提供商：谷歌 Nano Banana
该服务器使用 Gemini API [`interactions`](https://ai.google.dev/gemini-api/docs/image-generation) 端点用于 Nano Banana 模型。您需要对自己的 API 使用和成本负责。
## 许可证
[MIT](./LICENSE)
## 贡献
欢迎贡献！请在 GitHub 上提出问题或拉取请求。
