MCP Vision Server

为 DeepSeek V4 Pro 等无原生视觉能力的模型提供视觉服务的 MCP Server。

v0.2.0 — 现已支持多 Provider（OpenAI、OpenRouter、Groq、自定义端点等），自动按任务类型路由到最优模型。

功能

安装

pip install -e ".[dev]"

配置

级别 1：单 Provider（Agnes AI — 与 v0.1 完全兼容）

{
  "mcpServers": {
    "vision": {
      "command": "python",
      "args": ["-m", "mcp_vision_server"],
      "env": {
        "AGNES_API_KEY": "sk-xxx"
      }
    }
  }
}

级别 2：一键切换到 OpenAI

{
  "mcpServers": {
    "vision": {
      "command": "python",
      "args": ["-m", "mcp_vision_server"],
      "env": {
        "VISION_PROVIDER": "openai",
        "OPENAI_API_KEY": "sk-xxx"
      }
    }
  }
}

级别 3：按任务分配不同 Provider

{
  "mcpServers": {
    "vision": {
      "command": "python",
      "args": ["-m", "mcp_vision_server"],
      "env": {
        "VISION_PROVIDER": "openai",
        "IMAGE_PROVIDER": "agnes",
        "VIDEO_PROVIDER": "agnes",
        "OPENAI_API_KEY": "sk-openai-xxx",
        "AGNES_API_KEY": "sk-agnes-xxx",
        "VISION_MODEL": "gpt-4o",
        "IMAGE_GEN_MODEL": "dall-e-3"
      }
    }
  }
}

自定义端点（自部署模型）

{
  "mcpServers": {
    "vision": {
      "env": {
        "VISION_PROVIDER": "custom",
        "CUSTOM_BASE_URL": "http://localhost:8080/v1",
        "CUSTOM_API_KEY": "sk-local-xxx"
      }
    }
  }
}

支持的 Provider

环境变量完整参考

Provider 选择

模型覆盖

Agnes AI（向后兼容）

*如果只使用 Agnes 而不设置其他 Provider，则 AGNES_API_KEY 为必填。

其他 Provider 密钥

路由规则

工具调用时，Provider 选择优先级为：

1. 工具参数指定 — 如果 tool call 里传了 provider 参数
2. 环境变量按任务指定 — 如 IMAGE_PROVIDER=agnes
3. 全局默认 — VISION_PROVIDER 的值
4. 自动检测 — 第一个具有所需能力的已注册 Provider

使用示例

配置完成后，在 Claude Code 中直接使用：

• "帮我看看这张图片里有什么" → 自动调用 analyze_image
• "提取这张截图里的文字" → 自动调用 extract_text
• "生成一张猫的图片" → 自动调用 generate_image
• "分析这个视频的内容" → 自动调用 analyze_video
• "当前有哪些可用的 AI 服务？" → 自动调用 list_providers

测试

python -m pytest tests/ -v

技术栈

• Python 3.11+
• MCP SDK (stdio)
• httpx (HTTP)
• Pillow (图片处理)

MCP Hub 部署指南（自托管）

本仓库同时包含 MCP Hub（一个管理多个 MCP Server 的 Web 平台），采用 pnpm + turbo monorepo：

apps/
├── api/            # Fastify 5 后端（JWT + WebSocket + Bullmq 队列）
└── web/            # React 18 + Vite 7 + Tailwind 4 前端
packages/
├── data/           # Prisma 数据层（PostgreSQL）
└── shared/         # 跨端共享类型
docker-compose.yml  # PostgreSQL 17 + Redis 7

文档

• 用户使用教程 — 功能介绍与操作指引
• 运维手册 — 服务器运维、备份、排障、升级

MCP Hub 部署指南（自托管）

提供三个脚本（位于 scripts/）：

#### 适用环境

脚本针对自托管云服务器设计（已在阿里云上海验证）：

• Ubuntu 22.04 / 24.04 / 26.04
• 最低 2 核 2G / 20G SSD（建议 4G）
• 需开放端口：22（SSH）、8443（HTTPS）

#### 部署步骤

# 1. 克隆仓库（国内服务器推荐用 Gitee，速度快）
git clone https://gitee.com/rosecat2359/mcp-vision-server.git /opt/mcp-hub
# 或从 GitHub 克隆
# git clone https://github.com/rosecat2359/mcp-vision-server.git /opt/mcp-hub
cd /opt/mcp-hub

# 2. 执行部署（替换 你的域名）
sudo DOMAIN=你的域名 bash scripts/deploy.sh

部署脚本会自动完成：swap、ufw、Node 20、Docker、Caddy、pnpm、pm2、Prisma、构建、反向代理、HTTPS 证书签发。

#### 未备案服务器（大陆节点）

ICP 备案要求年满 18 周岁。若无法备案，脚本默认使用 8443 端口绕过 80/443 拦截：

• 访问地址：https://你的域名:8443
• 需在云厂商安全组放行 8443/TCP（脚本无法代替）
• 域名 A 记录需指向服务器公网 IP

环境变量

部署脚本自动生成（写入 apps/api/.env，首次生成后不覆盖）：

⚠️ 务必备份 `ENCRYPTION_MASTER_KEY`，服务器重装或迁移时需用同一密钥才能解密数据库中的凭据。

更新与卸载

# 更新到最新代码
sudo bash scripts/update.sh

# 标准卸载（保留代码和数据）
sudo bash scripts/uninstall.sh

# 彻底卸载（删除代码 + 数据库数据，不可逆）
sudo bash scripts/uninstall.sh --purge

常用运维命令

pm2 logs mcp-hub-api          # 查看后端日志
pm2 restart mcp-hub-api       # 重启后端
docker ps                     # 查看数据库容器
journalctl -u caddy -f        # 查看 Caddy/HTTPS 日志
docker compose logs -f        # 查看数据库日志

托管平台部署（可选）

如不自行部署，也可用托管服务：

• 前端：Vercel，Root Directory 设为 apps/web，Framework Preset = Vite
• 后端：Railway，从 GitHub 导入并配置环境变量
• 数据库：Neon / Supabase（PostgreSQL 免费档）+ Upstash（Redis 免费档）

注意：Vercel Hobby 计划不可商用；Railway 无长期免费计划。

开发

MCP Hub（TypeScript）

pnpm install
pnpm docker:up        # 启动本地 PostgreSQL + Redis
pnpm db:generate && pnpm db:push
pnpm dev              # 同时启动前端 (5173) 和后端 (3001)
pnpm test             # 运行测试
pnpm build            # 构建所有包

视觉服务（Python）

pip install -e ".[dev]"
python -m pytest tests/ -v