# NanoBanana MCP Server
一个封装 OpenRouter API 的 MCP (Model Context Protocol) 服务器，可供 Claude Code CLI、Claude Desktop 等 MCP 客户端使用。
## 功能特性
- 🚀 通过 MCP 协议访问 OpenRouter API
- 🤖 默认使用 Google Gemini 3 Pro Image Preview 模型
- 💬 支持聊天补全（Chat Completion）
- 📋 支持列出所有可用模型
- 🖼️ 支持文本和图像输入
## 📦 安装
### 方式 1: 通过 uvx（推荐）
使用 `uvx` 直接从 GitHub 运行，无需克隆仓库：
```bash
# 首先安装 uv（如果还没有）
pip install uv
```
#### 在 Claude Code CLI 中配置
编辑 Claude Code 配置文件并添加：
```json
{
"mcpServers": {
"nano-banana": {
"command": "uvx",
"args": ["nano-banana-mcp@git+https://github.com/caoshuo594/nano_banana.git"],
"env": {
"OPENROUTER_API_KEY": "sk-or-v1-your-actual-key-here"
}
}
}
}
```
#### 在 Claude Desktop 中配置
使用相同的配置格式。
### 方式 2: 克隆仓库（用于开发）
```bash
# 1. 克隆仓库
git clone https://github.com/caoshuo594/nano_banana.git
cd nano_banana
# 2. 安装依赖
pip install -r requirements.txt
```
#### 在 Claude Code CLI 中配置
```json
{
"mcpServers": {
"nano-banana": {
"command": "python",
"args": ["-m", "mcp_server"],
"cwd": "/path/to/nano_banana",
"env": {
"OPENROUTER_API_KEY": "sk-or-v1-your-actual-key-here"
}
}
}
}
```
#### 在 Claude Desktop 中配置
使用相同的配置格式。
### 🔑 获取 OpenRouter API Key
⚠️ **必需步骤**:
1. 访问 [OpenRouter](https://openrouter.ai/)
2. 注册/登录账号
3. 在 [API Keys 页面](https://openrouter.ai/keys) 创建新的 API Key
4. 复制您的 API Key（格式：`sk-or-v1-...`）
5. 在 Claude Desktop 配置的 `env` 部分填入
### 配置说明
- **API URL**: https://openrouter.ai/api/v1
- **默认模型**: google/gemini-3-pro-image-preview
**配置文件位置：**
- **Claude Code CLI**:
- **Windows**: `%APPDATA%\Claude Code\config.json`
- **macOS**: `~/Library/Application Support/Claude Code/config.json`
- **Linux**: `~/.config/claude-code/config.json`
- **Claude Desktop**:
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`
⚠️ **重要**:
- 将 `sk-or-v1-your-actual-key-here` 替换为您的实际 API Key
- 如果使用方式 2，将 `/path/to/nano_banana` 替换为实际路径
- 配置完成后重启 Claude Code CLI 或 Claude Desktop
## 🎨 使用方法
### 在 Claude Code CLI 中使用
配置完成后，在终端中启动 Claude Code，直接描述您的需求：
```bash
claude-code
# 或
claude code
# 然后输入：
帮我生成一张熊猫武士的图片
```
Claude 会自动：
1. 理解您的需求
2. 生成详细的提示词
3. 调用 MCP 图像生成工具
4. 返回 2 张高质量图片（base64 格式）
### 在 Claude Desktop 中使用
使用方式与 Claude Code CLI 相同，直接用自然语言描述需求即可。
### 直接测试（开发用）
可以使用 MCP Inspector 进行测试：
```bash
npx @modelcontextprotocol/inspector python mcp_server.py
```
## 可用工具
### 1. chat_completion
发送聊天补全请求到 OpenRouter API。
**参数**:
- `messages` (必需): 消息数组，每个消息包含 `role` 和 `content`
- `role`: "user", "assistant", 或 "system"
- `content`: 消息内容（文本或图像 URL）
- `model` (可选): 使用的模型，默认为 `google/gemini-3-pro-image-preview`
- `temperature` (可选): 采样温度 (0-2)，默认为 1
- `max_tokens` (可选): 生成的最大 token 数
- `stream` (可选): 是否流式返回，默认为 false
**示例**:
```json
{
"messages": [
{
"role": "user",
"content": "你好，请介绍一下自己"
}
],
"temperature": 0.7
}
```
### 2. list_models
列出 OpenRouter API 上所有可用的模型。
**参数**: 无
## 可用资源
### nano-banana://config
返回 NanoBanana MCP Server 的配置信息，包括 API URL 和默认模型。
## 架构说明
```
┌─────────────────┐
│ MCP 客户端 │
│ (Claude/Gemini) │
└────────┬────────┘
│ MCP Protocol
│ (stdio)
┌────────▼────────┐
│ MCP Server │
│ (mcp_server.py)│
└────────┬────────┘
│ HTTPS
│
┌────────▼────────┐
│ OpenRouter API │
│ (Gemini 3 Pro) │
└─────────────────┘
```
## 开发说明
### 项目结构
```
nano_banana/
├── mcp_server.py # MCP 服务器主程序
├── requirements.txt # Python 依赖
├── claude_desktop_config.json # Claude Desktop 配置示例
├── README.md # 本文档
├── nano_banana.md # API 配置信息
└── prompt.md # 项目需求说明
```
### 修改配置
如需修改 API Key 或默认模型，请编辑 `mcp_server.py` 中的以下常量：
```python
OPENROUTER_API_URL = "https://openrouter.ai/api/v1"
OPENROUTER_API_KEY = "your-api-key-here"
DEFAULT_MODEL = "google/gemini-3-pro-image-preview"
```
### 添加新工具
在 `mcp_server.py` 中：
1. 在 `list_tools()` 函数中添加新工具的定义
2. 在 `call_tool()` 函数中添加工具调用逻辑
3. 实现具体的工具函数
## 故障排除
### 问题：Claude Desktop 无法连接到 MCP 服务器
**解决方案**:
1. 检查 Python 是否在系统 PATH 中
2. 确认 `mcp_server.py` 的路径正确
3. 查看 Claude Desktop 的日志文件
4. 尝试手动运行 `python mcp_server.py` 检查是否有错误
### 问题：API 请求失败
**解决方案**:
1. 检查 API Key 是否有效
2. 确认网络连接正常
3. 查看 OpenRouter API 状态页面
4. 检查是否超出 API 配额
### 问题：依赖安装失败
**解决方案**:
```bash
# 升级 pip
python -m pip install --upgrade pip
# 重新安装依赖
pip install -r requirements.txt --force-reinstall
```
## 许可证
MIT License
## 贡献
欢迎提交 Issue 和 Pull Request！
## 相关链接
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [OpenRouter API](https://openrouter.ai/)
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
