# 豆包图片描述 MCP - 安装和使用指南
## 📋 目录
1. [快速开始](#快速开始)
2. [详细配置](#详细配置)
3. [iFlow CLI 集成](#iflow-cli-集成)
4. [Claude Desktop 集成](#claude-desktop-集成)
5. [使用示例](#使用示例)
6. [故障排除](#故障排除)
---
## 🚀 快速开始
### 第一步：安装依赖
打开终端或命令提示符，进入项目目录：
```bash
cd doubao-image-mcp
pip install -r requirements.txt
```
### 第二步：获取豆包 API Key
1. 访问 [火山引擎控制台](https://console.volcengine.com/)
2. 注册/登录账号
3. 开通"火山方舟"服务
4. 创建 API Key
5. **重要**：确保 API Key 有视觉理解模型的调用权限
### 第三步：配置
**方式 1：使用环境变量（推荐）**
Windows:
```cmd
set VOLCENGINE_API_KEY=你的API Key
```
Linux/Mac:
```bash
export VOLCENGINE_API_KEY=你的API Key
```
**方式 2：使用配置文件**
1. 复制配置示例：
```bash
cp config.example.json config.json
```
2. 编辑 `config.json`，填入你的 API Key：
```json
{
"VOLCENGINE_API_KEY": "你的豆包API Key（从火山引擎控制台获取）",
"DOUBAO_MODEL_ID": "doubao-seed-1-6-251015"
}
```
3. 设置环境变量指向配置文件：
```bash
# Windows
set CONFIG_FILE=config.json
# Linux/Mac
export CONFIG_FILE=config.json
```
### 第四步：添加到 iFlow CLI
```bash
iflow mcp add doubao-image-mcp python C:\Users\15579\doubao-image-mcp\server.py
```
### 第五步：测试
```bash
iflow
```
在 iFlow 中输入：
```
描述: https://picsum.photos/800/600
```
如果看到图片描述，说明配置成功！🎉
---
## 🔧 详细配置
### iFlow CLI 完整配置
编辑 `~/.iflow/settings.json`，添加到 `mcpServers` 部分：
```json
{
"mcpServers": {
"doubao-image-mcp": {
"command": "python",
"args": ["C:\\Users\\YourName\\doubao-image-mcp\\server.py"],
"env": {
"VOLCENGINE_API_KEY": "你的豆包API Key",
"DOUBAO_MODEL_ID": "doubao-seed-1-6-251015"
}
}
}
}
```
**注意**：将 `C:\\Users\\YourName\\doubao-image-mcp\\server.py` 替换为你的实际路径。
### Claude Desktop 配置
编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`：
```json
{
"mcpServers": {
"doubao-image-mcp": {
"command": "python",
"args": ["/Users/yourname/doubao-image-mcp/server.py"],
"env": {
"VOLCENGINE_API_KEY": "你的豆包API Key"
}
}
}
}
```
### 高级配置
#### 修改缓存目录
编辑 `server.py` 中的 `ImageDescriptionCache` 初始化：
```python
cache = ImageDescriptionCache(cache_dir="/your/custom/cache/dir")
```
#### 调整图片优化参数
编辑 `server.py` 中的配置：
```python
OPTIMIZE_SIZE = (1920, 1080) # 调整最大尺寸
OPTIMIZE_QUALITY = 85 # 调整 JPEG 质量 (1-100)
OPTIMIZE_MAX_SIZE_MB = 2 # 调整优化阈值 (MB)
```
#### 修改模型
```python
MODEL_ID = "doubao-seed-1-6-251015" # 或其他支持的模型
```
---
## 📱 iFlow CLI 集成
### 安装步骤
1. **确认安装位置**：
```bash
pwd # 查看当前目录
# 应该在 doubao-image-mcp 目录
```
2. **添加到 iFlow**：
```bash
iflow mcp add doubao-image-mcp python server.py
```
3. **验证安装**：
```bash
iflow mcp list
```
应该能看到 `doubao-image-mcp`
### 使用方法
在 iFlow CLI 中：
```bash
# 描述本地图片
描述: D:/Pictures/photo.jpg
# 描述网络图片
描述: https://example.com/image.jpg
# 批量描述
请描述这些图片：
1. D:/pic1.jpg
2. D:/pic2.png
3. https://example.com/pic3.jpg
```
---
## 💻 Claude Desktop 集成
### Windows 配置
1. 打开运行（Win+R），输入：
```
%APPDATA%\Claude
```
2. 编辑 `claude_desktop_config.json`：
```json
{
"mcpServers": {
"doubao-image-mcp": {
"command": "python",
"args": ["C:\\Users\\YourName\\doubao-image-mcp\\server.py"],
"env": {
"VOLCENGINE_API_KEY": "你的API Key"
}
}
}
}
```
3. 重启 Claude Desktop
### macOS 配置
1. 编辑配置文件：
```bash
nano ~/Library/Application\ Support/Claude/claude_desktop_config.json
```
2. 添加相同配置
3. 重启 Claude Desktop
---
## 🎯 使用示例
### 基础用法
```bash
# 最简单的方式
描述: /path/to/image.jpg
# 带自定义提示词
描述: /path/to/image.jpg，请详细描述图片中的颜色
```
### 高级用法
```bash
# 比较不同图片
请比较这两张图片的风格差异：
1. image1.jpg
2. image2.jpg
# 批量分析
请分析这些图片的共同主题：
- D:/photos/img1.jpg
- D:/photos/img2.jpg
- D:/photos/img3.jpg
```
### 组合使用
```bash
# 描述 + 提取信息
请描述这张图片，并提取其中的所有文字内容
# 描述 + 分析
描述: chart.jpg，请分析这个图表的数据趋势并给出结论
```
---
## 🔧 工具说明
### 1. `describe` - 智能描述（推荐）
**参数**：
- `image_input`: 图片路径或 URL
- `prompt`: 描述提示词（可选）
**示例**：
```
描述: photo.jpg
描述: photo.jpg，请用英文描述
```
**特点**：
- ✅ 自动识别本地文件或 URL
- ✅ 自动格式检测
- ✅ 自动缓存
- ✅ 自动优化（大图片）
### 2. `describe_image_from_file` - 本地文件
**参数**：
- `file_path`: 本地文件完整路径
**示例**：
```
使用 doubao-image-mcp 的 describe_image_from_file 工具描述：D:/photo.jpg
```
### 3. `describe_image_from_url` - 网络 URL
**参数**：
- `url`: 图片 URL（必须以 http:// 或 https:// 开头）
- `prompt`: 提示词（可选）
**示例**：
```
使用 doubao-image-mcp 的 describe_image_from_url 工具描述：https://example.com/image.jpg
```
### 4. `describe_image_from_base64` - Base64
**参数**：
- `base64_data`: Base64 编码的图片数据
- `prompt`: 提示词（可选）
**示例**：
```
使用 doubao-image-mcp 的 describe_image_from_base64 工具，数据是：[你的base64字符串]
```
---
## 🐛 故障排除
### 问题 1：命令未找到
**错误**：
```
错误: 工具 "describe" 未找到
```
**解决**：
1. 确认 MCP 已添加：
```bash
iflow mcp list
```
2. 重启 iFlow CLI
### 问题 2：API 调用失败
**错误**：
```
错误: 豆包客户端未正确初始化
```
**解决**：
1. 检查 API Key 是否正确
2. 检查网络连接
3. 确认火山方舟服务已开通
### 问题 3：文件不存在
**错误**：
```
错误: 文件不存在: D:\download\photo.jpg
```
**解决**：
1. 检查文件路径是否正确
2. 使用绝对路径而不是相对路径
3. 确认文件存在
### 问题 4：图片格式不支持
**错误**：
```
错误: 不支持的文件格式 '.pdf'
```
**解决**：
1. 检查文件扩展名
2. 确保是支持的格式：.jpg, .png, .gif, .webp, .bmp 等
### 问题 5：处理太慢
**症状**: 图片处理需要 4-5 分钟
**解决**：
1. 检查文件大小（应该 < 1MB）
2. 使用压缩工具：
```bash
python compress.py "大图片.jpg" "压缩后.jpg"
```
3. 调整图片分辨率到 1920x1080 或更小
### 问题 6：编码错误
**错误**：
```
Error code: 400 - Image dimensions are too small
```
**解决**：
- 确保图片尺寸至少 14x14 像素
- 大多数相机/手机的照片都符合要求
---
## 📞 获取帮助
- 查看 [README.md](README.md) 了解项目详情
- 查看 [论坛帖子.md](论坛帖子.md) 了解开发过程
- 提交 Issue 到 GitHub
---
**版本**: 1.0.0
**最后更新**: 2026-02-03
