Content
# Doubao Vision MCP Server
MCP (Model Context Protocol) based Doubao Vision model service, providing image recognition capabilities for Claude Code.
## ✨ Features
- 🖼️ **Image Recognition**: Supports local images and network image URLs
- 🤖 **Doubao Vision Model**: Uses `doubao-seed-2.0-pro` for image understanding
- 💬 **Custom Queries**: Allows free-form questions about images
- 📦 **uv Package Management**: Fast, isolated, and reproducible Python environments
- 🔒 **Security**: Manages API keys through environment variables
---
## 📋 Prerequisites
- Python 3.10 or higher
- [uv](https://github.com/astral-sh/uv) package manager
- Volc Engine API Key (enable Doubao Vision model service)
---
## 🚀 Quick Start
### 1️⃣ Clone the Project
```bash
git clone https://github.com/dehuadong/doubao-vision-mcp.git
cd doubao-vision-mcp
```
### 2️⃣ Install Dependencies
Requires Python 3.10+ and [uv](https://github.com/astral-sh/uv) package manager:
```bash
# Install uv (skip if already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh
# Install project dependencies
uv sync
```
### 3️⃣ Set Environment Variables
```bash
# Must be set
export DOUBAO_API_KEY="your Volc Engine API Key"
# Optional (default values shown)
export DOUBAO_MODEL="doubao-seed-2.0-pro"
export DOUBAO_ENDPOINT="https://ark.cn-beijing.volces.com/api/v3/chat/completions"
export DOUBAO_MAX_TOKENS="1000"
```
### 4️⃣ Test Run
```bash
uv run python server.py
```
Normal startup will wait for MCP protocol communication (no errors, press `Ctrl+C` to exit).
---
## 🔧 Configure Claude Code
Add via command line in Claude Code or configure in the project's root directory `.mcp.json`.
### Method 1: Use `claude mcp add` command (recommended ✅)
```bash
claude mcp add --transport stdio doubao-vision \
--env DOUBAO_API_KEY="your API Key" \
-- uv --directory /full/path/to/doubao-vision-mcp run python server.py
```
### Method 2: Use `.mcp.json` configuration file
Create `.mcp.json` in the project root directory:
```json
{
"mcpServers": {
"doubao-vision": {
"command": "uv",
"args": [
"--directory",
"/full/path/to/doubao-vision-mcp",
"run",
"python",
"server.py"
],
"env": {
"DOUBAO_API_KEY": "your API Key",
"DOUBAO_MODEL": "doubao-seed-2.0-pro"
}
}
}
}
```
### Method 3: Use system environment variables
If environment variables are already set using `export`, the `env` field can be omitted:
```json
{
"mcpServers": {
"doubao-vision": {
"command": "uv",
"args": [
"--directory",
"/full/path/to/doubao-vision-mcp",
"run",
"python",
"server.py"
]
}
}
}
```
**Configuration Instructions**:
- Replace `/full/path/to/doubao-vision-mcp` with your actual project path
- Recommended method 1 for centralized configuration, not dependent on external environment
- Suggested file permissions: `600` (owner read and write only)
---
## 🛠️ Available Tools
### `recognize_image`
Use Doubao Vision model to recognize image content. Supports local files and network URLs.
**Parameters**:
| Parameter | Type | Required | Description |
|------|------|------|------|
| `image` | string | ✅ | Local image absolute path or network URL |
| `prompt` | string | ❌ | Specific question about the image, automatically appended to default analysis prompt. Omit for general recognition |
**Supported Formats**: JPEG, PNG, GIF, WebP, BMP, TIFF, ICO, SVG
**Returns**: Text description structured as "main response → detailed observation → context and analysis → supplementary notes"
**Prompt Concatenation Mechanism**: The tool has a default analysis prompt (guides structured output). User-provided `prompt` is appended to the default prompt:
- No `prompt` → General recognition using default framework
- `prompt: "What animals are in the image?"` → Default framework + user's specific request
### Environment Variables
| Variable | Required | Default | Description |
|------|------|------|------|
| `DOUBAO_API_KEY` | ✅ | — | Volc Engine API Key |
| `DOUBAO_MODEL` | ❌ | `doubao-seed-2.0-pro` | Model name |
| `DOUBAO_ENDPOINT` | ❌ | `https://ark.cn-beijing.volces.com/api/v3/chat/completions` | API endpoint |
| `DOUBAO_MAX_TOKENS` | ❌ | `1000` | Maximum output tokens |
---
## 💡 Usage Examples
In Claude Code conversation:
```
Invoke recognize_image tool to recognize this image: /Users/me/photo.jpg
```
```
What's in this image? Image at https://example.com/cat.png
```
```
Invoke recognize_image tool to analyze this image and tell me the main colors and objects: ~/Pictures/screenshot.png
```
---
## 📦 Project Structure
```
doubao-vision-mcp/
├── server.py # Main service code
├── pyproject.toml # uv project configuration
├── README.md # This document
├── 提示词.md # Default analysis prompts
└── .gitignore # Git ignore rules
```
---
## 🔍 Troubleshooting
### 1. "Please set environment variable DOUBAO_API_KEY"
**Cause**: API Key not set or passed correctly
**Solution**:
```bash
export DOUBAO_API_KEY="your actual key"
```
or add in MCP configuration `env`
### 2. API call failure (HTTP 401)
**Cause**: API Key invalid or expired
**Solution**: Check Volc Engine console to confirm key validity and Doubao Vision model service enabled
### 3. Image file not found
**Cause**: Incorrect path or relative path issues
**Solution**: Use absolute path
### 4. uv command not found
**Cause**: uv not installed or not in PATH
**Solution**: Reinstall uv or restart terminal
### 5. ModuleNotFoundError
**Cause**: Dependencies not installed
**Solution**:
```bash
uv sync
```
---
## 📚 References
- [MCP Protocol Documentation](https://modelcontextprotocol.io)
- [Doubao Vision Model Documentation](https://www.volcengine.com/docs/82379)
- [uv Package Manager](https://docs.astral.sh/uv/)
---
## 📄 License
MIT License
---
**Enjoy using! 🎉**
