DeepSeek-OCR Agent for Claude Code

针对Claude Code的DeepSeek-OCR集成实现。通过Modal Labs在GPU上运行DeepSeek-OCR，提供高精度的OCR处理。

特性

• 高精度OCR: DeepSeek-OCR提供的97-98%的精度
• 多语言支持: 支持包括日语、英语、中文在内的100多种语言
• 成本优化: Modal Labs的免费额度（每月$30）足以覆盖个人使用
• Claude Code集成: 通过MCP服务器无缝使用
• 子代理支持: 使用ocr-specialist代理进行专业OCR处理

架构

Claude Code (Mac)
  └─ MCP Server (Node.js/TypeScript)
      └─ Modal Labs API
          └─ Modal Functions (Python)
              └─ DeepSeek--OCR (GPU: T4, 8GB VRAM)

需求

软件

• Python 3.12+: 运行Modal CLI
• Node.js 18+: 运行MCP服务器
• Modal Labs账户: 在modal.com免费注册

系统需求

• macOS（兼容Apple Silicon / Intel）
• 网络连接（用于Modal Labs API）

设置

1. 快速开始

# 运行设置脚本
./scripts/setup.sh

此脚本会自动执行以下操作:

• 检查Python/Node.js环境
• 安装Modal CLI
• 认证Modal
• 部署Modal应用
• 构建MCP服务器
• 引导Claude Desktop设置

2. 手动设置

第一步: 安装Modal CLI

pip3 install modal

第二步: 认证Modal

modal token new

浏览器将打开，登录或注册Modal Labs并生成令牌。

第三步: 部署Modal应用

cd modal_app
modal deploy main.py

第四步: 构建MCP服务器

cd mcp-server
npm install
npm run build

第五步: 设置Claude Desktop

在~/Library/Application Support/Claude/claude_desktop_config.json中添加以下内容:

{
  "mcpServers": {
    "deepseek-ocr": {
      "command": "node",
      "args": [
        "/Users/username/deepseek-ocr-agent/mcp-server/dist/index.js"
      ]
    }
  }
}

重要: 将路径替换为实际项目路径。

第六步: 重启Claude Desktop

为了使设置生效，请重启Claude Desktop。

使用方法

在Claude Code中的基本使用

1. 将图像转换为Markdown

   将此图像转换为Markdown: /path/to/document.png
   

2. 提取纯文本

   从此收据中提取文本: receipt.jpg
   

3. 自定义提示

   仅从此图像中提取表格数据并以CSV格式呈现: table.png
   

子代理的使用

对于OCR专业任务，可以使用ocr-specialist子代理:

@ocr-specialist 将此文档数字化

详细的使用方法请参阅 USAGE.md。

成本

Modal Labs费用

• 免费额度: 每月$30的信用额度
• GPU (T4): $0.000164/秒

月度成本估算

个人使用（每天100张，每月3,000张）:

处理时间: 3,000张 × 3秒 = 9,000秒
成本: $0.000164 × 9,000 = $1.48/月
免费额度: $30/月

→ 实际成本$0（在免费额度内）

每月最多可处理10,000张图片。

故障排除

Modal认证错误

modal token new

重新生成令牌。

MCP服务器未被识别

1. 重启Claude Desktop
2. 检查配置文件路径
3. 确认MCP服务器已构建: ls mcp-server/dist/index.js

OCR处理失败

• 确认图像文件存在
• 确认图像格式受支持（推荐PNG, JPG, JPEG）
• 确认Modal应用已部署: modal app list

处理速度慢

• 首次运行时会有冷启动（5-10秒）
• 第二次及以后运行时会缩短至2-3秒

测试

功能测试

# 准备测试用图像
./scripts/test-ocr.sh /path/to/test/image.png

MCP服务器测试

cd mcp-server
npm run dev

项目结构

deepseek-ocr-agent/
├── modal_app/              # Modal Functions（Python）
│   ├── main.py             # DeepSeek-OCR处理的主要实现
│   └── requirements.txt    # Python依赖项
│
├── mcp-server/             # MCP服务器（TypeScript）
│   ├── src/
│   │   ├── index.ts        # MCP服务器主体
│   │   └── tools/
│   │       └── modal-ocr.ts # Modal API集成
│   ├── package.json
│   └── tsconfig.json
│
├── .claude/
│   └── agents/
│       └── ocr-specialist.md # OCR专业子代理
│
├── scripts/
│   ├── setup.sh            # 设置脚本
│   └── test-ocr.sh         # 测试脚本
│
├── config/
│   ├── claude_desktop_config.json  # Claude Desktop配置示例
│   └── .env.example        # 环境变量示例
│
├── docs/                   # 文档
│   ├── USAGE.md            # 使用指南
│   ├── DEPLOYMENT.md       # 部署指南
│   └── SUMMARY.md          # 实现概要
│
└── README.md

技术栈

后端（Modal Functions）

• Python 3.12
• PyTorch 2.6.0
• Transformers 4.46.3
• DeepSeek-OCR（deepseek-ai/DeepSeek-OCR）
• Flash Attention 2.7.3

MCP服务器

• Node.js 18+
• TypeScript 5.7
• @modelcontextprotocol/sdk
• Axios

基础设施

• Modal Labs（无服务器GPU）
• NVIDIA T4 GPU（8GB VRAM）

文档

详细的文档位于 docs/ 目录下:

• USAGE.md: 使用方法和实用示例
• DEPLOYMENT.md: 部署和监控
• SUMMARY.md: 实现概要

常见问题

Apple Silicon Mac上能运行吗？

是的。本地不使用GPU，而是通过Modal Labs使用云GPU（NVIDIA T4），因此无论是Apple Silicon还是Intel都能运行。

可以离线使用吗？

不可以。因为需要使用Modal Labs API，所以必须有网络连接。

可以商业使用吗？

DeepSeek-OCR采用MIT许可证。请查阅Modal Labs的使用条款。

更多问题请参阅 USAGE.md 中的FAQ部分。

许可证

MIT License

参考链接

• DeepSeek-OCR GitHub
• Modal Labs
• Claude Code Documentation
• Model Context Protocol

贡献

欢迎提交Issue和Pull Request。

支持

遇到问题时:

1. 查看此README中的故障排除部分
2. 在GitHub上创建Issue
3. 参考Modal Labs 文档