Skip to main content
Glama
dehuadong

Doubao Vision MCP Server

by dehuadong
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Doubao Vision MCP Server

基于 MCP (Model Context Protocol) 的豆包视觉模型服务，为 Claude Code 提供图片识别能力。

✨ 功能特性

  • 🖼️ 图片识别：支持本地图片和网络图片 URL

  • 🤖 豆包视觉模型：使用 doubao-seed-2.0-pro 进行图像理解

  • 💬 自定义提问：可针对图片自由提问

  • 📦 uv 包管理：快速、隔离、可重现的 Python 环境

  • 🔒 安全：通过环境变量管理 API 密钥

Related MCP server: gemini-nano-banana-mcp

📋 前置要求

  • Python 3.10 或更高版本

  • uv 包管理器

  • 火山引擎 API Key（开通豆包视觉模型服务）

🚀 快速开始

1️⃣ 克隆项目

git clone https://github.com/dehuadong/doubao-vision-mcp.git
cd doubao-vision-mcp

2️⃣ 安装依赖

需要 Python 3.10+ 和 uv 包管理器：

# 安装 uv（如已安装可跳过）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 安装项目依赖
uv sync

3️⃣ 设置环境变量

# 必须设置
export DOUBAO_API_KEY="你的火山引擎 API Key"

# 可选（默认值如下）
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️⃣ 测试运行

uv run python server.py

正常启动后会等待 MCP 协议通信（无报错即可，按 Ctrl+C 退出）。

🔧 配置 Claude Code

在 Claude Code 中通过命令行添加，或在项目根目录的 .mcp.json 中配置。

方式一：使用 claude mcp add 命令（推荐 ✅）

claude mcp add --transport stdio doubao-vision \
  --env DOUBAO_API_KEY="你的API密钥" \
  -- uv --directory /完整路径/to/doubao-vision-mcp run python server.py

方式二：使用 .mcp.json 配置文件

在项目根目录创建 .mcp.json：

{
  "mcpServers": {
    "doubao-vision": {
      "command": "uv",
      "args": [
        "--directory",
        "/完整路径/to/doubao-vision-mcp",
        "run",
        "python",
        "server.py"
      ],
      "env": {
        "DOUBAO_API_KEY": "你的API密钥",
        "DOUBAO_MODEL": "doubao-seed-2.0-pro"
      }
    }
  }
}

方式三：使用系统环境变量

如果已经通过 export 设置了环境变量，可以省略 env 字段：

{
  "mcpServers": {
    "doubao-vision": {
      "command": "uv",
      "args": [
        "--directory",
        "/完整路径/to/doubao-vision-mcp",
        "run",
        "python",
        "server.py"
      ]
    }
  }
}

配置说明：

  • 将 /完整路径/to/doubao-vision-mcp 替换为你的实际项目路径

  • 推荐方式一，配置集中，不依赖外部环境

  • 配置文件权限建议设为 600（仅所有者可读写）

🛠️ 可用工具

recognize_image

使用豆包视觉模型识别图片内容。支持本地文件和网络 URL。

参数：

参数

类型

必填

描述

image

string

✅

本地图片绝对路径或网络 URL

prompt

string

❌

对图片的具体提问，会自动拼接到默认分析提示词末尾。不填则仅用默认分析框架进行通用识别

支持格式：JPEG、PNG、GIF、WebP、BMP、TIFF、ICO、SVG

返回：模型按「主要回应 → 详细观察 → 上下文与分析 → 补充说明」结构输出的文本描述

Prompt 拼接机制：工具内置默认分析提示词（引导模型结构化输出），不会因为提供 prompt 参数而被丢弃。用户传入的 prompt 会自动拼接到默认提示词末尾：

  • 不传 prompt → 仅使用默认分析框架进行通用识别

  • 传 prompt: "图中有什么动物" → 默认分析框架 + 用户的具体要求：图中有什么动物

环境变量

变量

必填

默认值

描述

DOUBAO_API_KEY

✅

—

火山引擎 API Key

DOUBAO_MODEL

❌

doubao-seed-2.0-pro

模型名称

DOUBAO_ENDPOINT

❌

https://ark.cn-beijing.volces.com/api/v3/chat/completions

API 端点

DOUBAO_MAX_TOKENS

❌

1000

最大输出 token 数

💡 使用示例

在 Claude Code 对话中：

调用 recognize_image 工具,识别这张图片：/Users/me/photo.jpg
这张图里有什么？图片在 https://example.com/cat.png
调用 recognize_image 工具分析这张图片，告诉我主要颜色和物体：~/Pictures/screenshot.png

📦 项目结构

doubao-vision-mcp/
├── server.py                # 主服务代码
├── pyproject.toml           # uv 项目配置
├── README.md                # 本文档
├── 提示词.md                 # 默认分析提示词
└── .gitignore               # Git 忽略规则

🔍 故障排查

1. 提示 "请设置环境变量 DOUBAO_API_KEY"

原因：未设置或未正确传递 API Key

解决：

export DOUBAO_API_KEY="你的真实密钥"

或在 MCP 配置的 env 中添加

2. API 调用失败 (HTTP 401)

原因：API Key 无效或过期

解决：检查火山引擎控制台，确认密钥有效且已开通豆包视觉模型服务

3. 图片文件不存在

原因：路径错误或相对路径问题

解决：使用绝对路径

4. uv 命令未找到

原因：uv 未安装或未加入 PATH

解决：重新安装 uv 或重启终端

5. ModuleNotFoundError

原因：依赖未安装

解决：

uv sync

📚 参考资料

📄 许可证

MIT License

祝你使用愉快！ 🎉

Available Tools

1 tool
recognize_image识别图片A
Read-only

使用豆包视觉模型（doubao-seed-2.0-pro）识别图片内容。支持本地绝对路径和网络 URL。返回模型的文字描述，可用于物体识别、文字提取、场景理解等。不支持视频或非图片文件。

ParametersJSON Schema
NameRequiredDescriptionDefault
imageYes图片的本地绝对路径（如 /home/user/photo.jpg）或网络 URL（如 https://example.com/cat.png）
promptNo对图片的具体提问，如 '图中有什么物体'、'这张图的主色调是什么'。不填则仅使用默认分析框架进行通用识别。填写后会自动拼接到默认分析提示词末尾，引导模型按「主要回应→详细观察→上下文与分析→补充说明」结构输出。

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already provide readOnlyHint and openWorldHint. The description adds specific behavioral details: the exact model used (doubao-seed-2.0-pro), that it requires absolute paths or URLs, and limitations (no video/non-images). This goes beyond annotations without contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise (5 short sentences) with front-loaded purpose. Every sentence adds information: model, supported inputs, return, use cases, and limitations. No redundant or filler content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given only 2 parameters with full schema coverage, no output schema, and annotations present, the description covers all key aspects: functionality, input formats, return, model, and limitations. It could mention output details (e.g., JSON structure) but is adequate for its simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with parameter descriptions. The tool description adds extra semantics for the 'prompt' parameter, explaining that leaving it blank uses a default analysis framework and that filling it appends to the prompt and guides output structure. This adds value beyond the schema alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool uses a specific visual model to recognize image content. It specifies supported input types (local path and URL), return format (text description), and use cases. It also explicitly states what it does not support (video/non-image files), effectively distinguishing the tool even without siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides when-to-use context by listing use cases like object recognition and text extraction, and explicitly states non-support for video/files. However, it lacks explicit guidance on when to prefer this tool over alternatives, and there are no sibling tools to compare.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 1 tool updatev0.2.0
    • First observedrecognize_image
Deploy Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4/5.0

Scored across 1 tool

Disambiguation5/5

Single tool with a clear, distinct purpose: image recognition. No ambiguity with other tools.

Naming Consistency4/5

The tool name 'recognize_image' follows a clear verb_noun pattern. Though only one tool exists, the naming is well-structured and conventional.

Tool Count3/5

One tool is on the thin side for a 'Vision' server, but it serves a focused purpose. The count is borderline acceptable.

Completeness2/5

The server name implies broader vision capabilities, yet only image recognition is provided. Missing tools for model info, image metadata, or other vision tasks create significant gaps.

Maintenance

ActivityStale
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers