# 豆包图片描述 MCP - 使用说明
## 项目结构
```
doubao-image-mcp/
├── server.py # MCP 服务器主代码
├── claude_desktop_config.json # Claude Desktop 配置示例
├── README.md # 项目说明
├── install.sh # Linux/macOS 安装脚本
├── install.bat # Windows 安装脚本
└── .gitignore # Git 忽略文件
```
## 安装步骤
### Windows 用户
1. 双击运行 `install.bat` 或在命令行中执行:
```cmd
install.bat
```
2. 或手动安装:
```cmd
pip install mcp[cli] volcengine-python-sdk[ark] httpx
```
### Linux/macOS 用户
1. 运行安装脚本:
```bash
chmod +x install.sh
./install.sh
```
2. 或手动安装:
```bash
pip install mcp[cli] volcengine-python-sdk[ark] httpx
```
## 运行服务器
```bash
# Windows
python server.py
# Linux/macOS
python3 server.py
```
## 配置 Claude Desktop
### 步骤 1: 找到配置文件
**Windows:**
- 路径: `%APPDATA%\Claude\claude_desktop_config.json`
- 完整路径示例: `C:\Users\15579\AppData\Roaming\Claude\claude_desktop_config.json`
**macOS:**
- 路径: `~/Library/Application Support/Claude/claude_desktop_config.json`
- 完整路径示例: `/Users/15579/Library/Application Support/Claude/claude_desktop_config.json`
### 步骤 2: 编辑配置文件
将以下内容添加到配置文件中 (注意保持正确的 JSON 格式):
```json
{
"mcpServers": {
"doubao-image": {
"command": "python",
"args": ["C:\Users\15579\doubao-image-mcp\server.py"],
"env": {
"VOLCENGINE_API_KEY": "9b80e24d-3d98-4ce6-a574-b697ce11689e"
}
}
}
}
```
**注意**:
- 如果已有其他 MCP 服务器配置,只需在 `mcpServers` 对象中添加 `doubao-image` 部分
- 确保所有逗号和括号都正确
- 可以使用在线 JSON 验证工具检查格式
### 步骤 3: 重启 Claude Desktop
关闭并重新打开 Claude Desktop,让它加载新的 MCP 服务器。
## 使用方法
### 在 Claude 中的使用示例
#### 示例 1: 描述本地图片
```
请描述这张图片: C:\Users\15579\Pictures\sunset.jpg
```
或者:
```
使用 doubao-image 分析这张图片: C:\Users\15579\Documents\photo.png
```
#### 示例 2: 描述网络图片
```
分析这张图片: https://example.com/image.jpg
```
```
请详细描述这个 URL 的图片内容: https://ark-project.tos-cn-beijing.volces.com/doc_image/ark_demo_img_1.png
```
#### 示例 3: 粘贴图片
在某些支持粘贴图片的应用中(如网页版的 Claude),你可以:
1. 复制一张图片
2. 粘贴到对话框中
3. Claude 会自动识别并调用 `describe_image_from_base64` 工具
### 可用的工具
#### 1. describe_image_from_file
**功能**: 从本地文件路径描述图片
**参数**:
- `file_path` (string, 必需): 图片文件的绝对路径
**示例提示词**:
- "请描述 C:\Users\15579\Desktop\test.jpg 这张图片"
- "分析这张图片的内容: /path/to/image.png"
---
#### 2. describe_image_from_base64
**功能**: 从 Base64 编码描述图片
**参数**:
- `base64_data` (string, 必需): Base64 编码的图片数据
- `prompt` (string, 可选): 自定义提示词,默认为"请详细描述这张图片的内容"
**使用场景**:
- 从剪贴板粘贴的图片
- 程序生成的图片数据
- 不存储在本地的图片
**示例提示词**:
- "分析这张 base64 图片: iVBORw0KGgo..."
- "用中文描述这张图片: [base64数据]"
---
#### 3. describe_image_from_url
**功能**: 从网络 URL 描述图片
**参数**:
- `url` (string, 必需): 图片的 URL 地址
- `prompt` (string, 可选): 自定义提示词
**示例提示词**:
- "请描述 https://example.com/photo.jpg 这张图片"
- "详细分析这张网络图片的内容: [URL]"
## 故障排除
### 问题 1: Claude Desktop 看不到工具
**可能原因**:
1. 配置文件格式错误
2. 服务器未正确启动
3. Claude Desktop 未重启
**解决方法**:
1. 使用 JSON 验证工具检查配置文件格式
2. 在命令行运行 `python server.py` 测试服务器
3. 完全关闭 Claude Desktop 后重新打开
### 问题 2: API 调用失败
**可能原因**:
1. API Key 无效
2. 网络连接问题
3. 豆包服务暂时不可用
**解决方法**:
1. 检查 API Key 是否正确
2. 测试网络连接
3. 查看服务器日志(命令行输出)
4. 访问[火山引擎控制台](https://console.volcengine.com/ark)确认服务状态
### 问题 3: 找不到文件
**错误信息**: "文件不存在: xxx"
**解决方法**:
1. 确认使用的是绝对路径(如 `C:\Users\15579\Pictures\photo.jpg`)
2. 检查文件路径是否正确
3. 确认文件确实存在
### 问题 4: 依赖安装失败
**错误信息**: "No module named 'xxx'"
**解决方法**:
```bash
# 重新安装依赖
pip install --upgrade mcp[cli] volcengine-python-sdk[ark] httpx
# 或使用国内镜像源
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple mcp[cli] volcengine-python-sdk[ark] httpx
```
## 进阶使用
### 自定义提示词
你可以在调用工具时提供更具体的提示词:
```
请用中文描述这张图片的主要元素: C:\Users\15579\Pictures\art.jpg
```
工具会使用"请用中文描述这张图片的主要元素"作为提示词,而不是默认的"请详细描述这张图片的内容"。
### 批量处理
如果你需要描述多张图片,可以这样问:
```
请分别描述以下图片:
1. C:\Users\15579\Pictures\photo1.jpg
2. C:\Users\15579\Pictures\photo2.jpg
```
Claude 会依次调用工具描述每张图片。
## 技术细节
### 使用的模型
- **默认模型**: `doubao-vision-pro` (豆包视觉理解专业版)
- **能力**: 支持图片内容描述、物体识别、场景理解等
### API 调用方式
- 使用火山引擎 Ark SDK
- 基于 FastMCP 框架
- 支持 stdio 传输
### 支持的图片格式
- JPG/JPEG
- PNG
- GIF
- BMP
- WEBP
- 其他常见图片格式
### 图片大小限制
- 建议单个文件不超过 10MB
- Base64 编码后会增大约 33%,注意总大小
## 相关资源
- [豆包大模型官方文档](https://www.volcengine.com/docs/82379/1362931)
- [MCP 官方文档](https://modelcontextprotocol.io)
- [火山引擎控制台](https://console.volcengine.com/ark)
## 更新日志
### v0.1.0 (2025-02-02)
- ✅ 初始版本发布
- ✅ 支持三种输入方式(文件、Base64、URL)
- ✅ 集成豆包视觉理解模型
- ✅ 完整的错误处理和日志
## 许可证
MIT License
---
**有问题?** 查看 README.md 或提交 Issue
