# 豆包图片描述 MCP 服务器
> 为 iFlow CLI 和 Claude Desktop 提供豆包视觉理解能力的 MCP 服务器
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/))
[](https://modelcontextprotocol.io/)
## ✨ 特性
- ⚡ **快速响应**：首次查询 20-30 秒，缓存命中 < 0.1 秒
- 🎯 **智能识别**：自动识别本地文件和网络 URL
- 🖼️ **格式支持**：18 种图片格式（JPG、PNG、GIF、WEBP 等）
- 🗜️ **自动优化**：大图片自动压缩（可配置）
- 💾 **智能缓存**：基于文件内容哈希的缓存系统
- 🌏 **中文优化**：专为豆包模型优化
## 🚀 快速开始
### 1. 安装依赖
```bash
pip install -r requirements.txt
```
### 2. 配置 API Key
**方式一：环境变量**（推荐）
```bash
# Windows (PowerShell)
$env:VOLCENGINE_API_KEY="你的豆包API Key"
# Linux/Mac
export VOLCENGINE_API_KEY="你的豆包API Key"
```
**方式二：配置文件**
```bash
# 复制配置示例
cp config.example.json config.json
# 编辑 config.json，填入你的 API Key
```
### 3. 添加到 iFlow CLI
```bash
iflow mcp add doubao-image-mcp python C:\Users\15579\doubao-image-mcp\server.py
```
### 4. 测试
```bash
iflow
> 描述: https://picsum.photos/800/600
```
## 📖 使用方法
### 描述本地文件
```bash
描述: D:/download/photo.jpg
```
### 描述网络图片
```bash
描述: https://example.com/image.jpg
```
### 自定义提示词
```bash
描述: photo.jpg，请用英文描述
描述: photo.jpg，请提取所有文字内容
```
## 🛠️ 工具列表
### 1. `describe` ⭐ 推荐
智能描述图片，自动识别 URL 或文件路径
### 2. `describe_image_from_file`
描述本地图片文件
### 3. `describe_image_from_url`
描述网络图片 URL
### 4. `describe_image_from_base64`
描述 Base64 编码的图片
## ⚙️ 配置选项
### 环境变量
| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `VOLCENGINE_API_KEY` | 豆包 API Key | 必填 |
| `DOUBAO_MODEL_ID` | 模型 ID | `doubao-seed-1-6-251015` |
### 图片优化配置
在 `server.py` 中可调整：
```python
OPTIMIZE_SIZE = (1920, 1080) # 最大尺寸
OPTIMIZE_QUALITY = 85 # JPEG 质量 (1-100)
OPTIMIZE_MAX_SIZE_MB = 2 # 超过此值自动优化
```
## 📊 性能
| 场景 | 时间 | 说明 |
|------|------|------|
| 首次查询 | 20-30秒 | 取决于图片大小和网络 |
| 缓存命中 | <0.1秒 | 99.5% 性能提升 |
| 大文件(5MB) | 15-20秒 | 自动优化后 |
| 小文件(<500KB) | 8-12秒 | 最佳体验 |
## 🐛 常见问题
### Q: 图片处理需要 4-5 分钟？
**A**: 图片太大了！压缩到 < 1MB 即可。
### Q: 支持哪些格式？
**A**: `.jpg`, `.png`, `.gif`, `.webp`, `.bmp`, `.tiff`, `.heic`, `.raw` 等 18 种格式。
### Q: 如何获取 API Key？
**A**: 访问[火山引擎控制台](https://console.volcengine.com/)，开通火山方舟服务后创建。
### Q: 可以在 Claude Desktop 使用吗？
**A**: 可以！参考配置说明。
## 📦 项目结构
```
doubao-image-mcp/
├── server.py # MCP 服务器主程序
├── config.example.json # 配置示例
├── requirements.txt # Python 依赖
├── compress.py # 图片压缩工具
├── diagnose_speed.py # 速度诊断工具
└── README.md # 本文件
```
## 🤝 贡献
欢迎提 Issue 和 Pull Request！
## 📄 License
MIT License
## 🔗 相关链接
- [iFlow CLI](https://github.com/iflow-ai/iflow-cli)
- [MCP 协议](https://modelcontextprotocol.io/)
- [豆包大模型](https://www.volcengine.com/product/doubao)
- [火山方舟](https://www.volcengine.com/product/volcengine)
---
**开发者**: [Your Name]
**版本**: 1.0.0
**最后更新**: 2026-02-03
