MZ-MCP - 华为云 OCR MCP 服务器

一个基于 Model Context Protocol (MCP) 的服务器，通过华为云 OCR 服务提供光学字符识别（OCR）功能。

功能特性

• 通用文本识别：从图像中提取文本，支持多种格式（JPG、PNG、BMP、GIF、TIFF、WEBP、PCX、ICO、PSD、PDF）
• 倾斜校正：自动检测并校正图片的倾斜角度
• 多语言支持：支持 30 多种语言的文字识别，包括中文、英文、日语、韩语等
• 快速模式：针对单行文字图片提供快速识别
• 单字符模式：返回字符级别的详细信息
• PDF 支持：支持多页 PDF 文件的文字识别
• 双输出格式：支持人类可读的 Markdown 格式和机器可读的 JSON 格式
• 完善的错误处理：为各种故障场景提供清晰、可操作的错误消息
• 输入验证：基于 Zod 的运行时参数验证
• STDIO 传输：通过标准输入/输出通信，易于集成

前置要求

• Node.js >= 18
• 华为云账号，已开通 OCR 服务
• 从 华为云 IAM 控制台 获取的访问密钥（AK/SK）和项目 ID

安装

通过 npx 使用（推荐）

无需安装，直接使用：

npx -y mz-mcp-beta@beta

本地安装

npm install mz-mcp-beta

配置

环境变量

配置以下必需的环境变量：

| 环境变量 | 必需 | 说明 | |---------|------|------| | CLOUD_SDK_AK | 是 | 华为云访问密钥 ID | | CLOUD_SDK_SK | 是 | 华为云秘密访问密钥 | | HUAWEI_OCR_PROJECT_ID | 是 | 华为云项目 ID | | HUAWEI_OCR_REGION | 否 | 服务地域，默认为 cn-east-3（华东-上海） |

获取凭证

1. 登录 华为云控制台
2. 进入"我的凭证" → "访问密钥"
3. 点击"新增访问密钥"，下载 .csv 文件
4. 进入"我的凭证" → "API凭证"，查看项目 ID

详细步骤请参考 华为云 API 签名指南 - 获取 AK/SK

MCP 客户端配置

将此服务器添加到您的 MCP 客户端配置中：

{
  "mcpServers": {
    "huawei-ocr": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "mz-mcp"
      ],
      "env": {
        "CLOUD_SDK_AK": "your_access_key",
        "CLOUD_SDK_SK": "your_secret_key",
        "HUAWEI_OCR_PROJECT_ID": "your_project_id",
        "HUAWEI_OCR_REGION": "cn-east-3"
      }
    }
  }
}

支持的服务地域

| 区域代码 | 区域名称 | |---------|---------| | cn-north-4 | 华北-北京四 | | cn-east-3 | 华东-上海 | | cn-south-1 | 华南-广州 | | ap-southeast-1 | 中国-香港 |

开发

克隆仓库

git clone https://github.com/xiaomizhoubaobei/MZ-MCP.git
cd MZ-MCP

安装依赖

npm install

配置环境变量

cp .env.example .env
# 编辑 .env 文件，填入您的华为云凭证

构建

npm run build

开发模式

npm run dev

生产模式

npm start

工具

huawei_ocr_recognize_general_text

从图像中识别通用文本。

参数

| 参数 | 类型 | 必需 | 说明 | |------|------|------|------| | image | string | 否* | Base64 编码的图像数据（与 url 二选一） | | url | string | 否* | 图像的公开 URL（与 image 二选一） | | detect_direction | boolean | 否 | 是否校正图片的倾斜角度（默认：false） | | quick_mode | boolean | 否 | 快速模式开关，针对单行文字图片（默认：false） | | character_mode | boolean | 否 | 单字符模式开关（默认：false） | | language | string | 否 | 语种选择，默认为中英文识别模式 | | single_orientation_mode | boolean | 否 | 单朝向模式开关（默认：false） | | pdf_page_number | number | 否 | 指定 PDF 页码识别（默认：第1页） | | return_markdown_result | boolean | 否 | 是否返回文字块拼接结果（默认：false） | | response_format | 'markdown' | 'json' | 否 | 输出格式（默认：'markdown'） |

*必须提供 image 或 url 中的一个。

支持的语种

| 语种代码 | 语言名称 | |---------|---------| | auto | 自动语种分类 | | zh | 中英文 | | en | 英文 | | ja | 日语 | | ko | 韩语 | | ru | 俄语 | | de | 德语 | | fr | 法语 | | es | 西班牙语 | | pt | 葡萄牙语 | | it | 意大利语 | | ar | 阿拉伯语 | | th | 泰语 | | vi | 越南语 | | id | 印尼语 | | ms | 马来语 | | hi | 印地语 | | uk | 乌克兰语 | | tr | 土耳其语 | | no | 挪威语 | | da | 丹麦语 | | sv | 瑞典语 | | km | 柬埔寨语 | | he | 希伯来语 |

图像格式要求

• 支持格式：JPEG、JPG、PNG、BMP、GIF、TIFF、WEBP、PCX、ICO、PSD、PDF
• 图片大小：Base64 编码后不超过 10MB，建议不超过 7MB
• 图片尺寸：最短边不小于 15px，最长边不超过 30000px
• URL 要求：支持公网 http/https URL 和 OBS URL

使用示例

在支持 MCP 的 AI 助手中，您可以直接通过自然语言使用此工具：

示例 1：识别图片中的文字

用户：请帮我识别这张图片中的文字

AI 助手会自动调用 huawei_ocr_recognize_general_text 工具，传入图片数据，返回识别结果。

示例 2：识别日语文本

用户：这张图片是日文的，帮我识别一下内容

AI 助手会自动设置 language: "ja" 参数进行日语识别。

示例 3：识别 PDF 文档

用户：请读取这个 PDF 文件的第 3 页内容

AI 助手会自动设置 pdf_page_number: 3 参数识别指定页面。

示例 4：校正倾斜图片

用户：这张图片有点歪，帮我识别里面的文字

AI 助手会自动设置 detect_direction: true 参数进行倾斜校正。

示例 5：快速识别单行文字

用户：这是车牌号，快速识别一下

AI 助手会自动设置 quick_mode: true 参数进行快速识别。

输出格式

Markdown 格式：

# OCR 识别结果

## 检测到的文本
1. 第一行文字
2. 第二行文字
3. 第三行文字

## 元数据
- **总字符数**: 42
- **总行数**: 3
- **处理时间**: 0.23 秒

JSON 格式：

{
  "result": {
    "direction": 67.6506,
    "words_block_count": 3,
    "words_block_list": [
      {
        "words": "第一行文字",
        "confidence": 0.98,
        "location": [[517, 447], [540, 504], [505, 518], [482, 461]],
        "char_list": [
          {
            "char": "第",
            "char_location": [[517, 447], [530, 479], [495, 493], [482, 461]],
            "char_confidence": 0.99
          }
        ]
      }
    ],
    "markdown_result": "第一行文字\t第二行文字\t第三行文字\n"
  },
  "metadata": {
    "total_characters": 42,
    "total_lines": 3,
    "processing_time_ms": 230
  }
}

错误处理

服务器为常见问题提供清晰的错误消息：

HTTP 状态码错误

• 400：无效请求 - 检查图像格式和大小，确认 image 和 url 参数二选一
• 401：认证失败 - 检查您的凭证（AK/SK）
• 403：权限被拒绝 - 验证 IAM 权限
• 429：超出速率限制 - 等待后重试
• 500：内部服务器错误 - 稍后重试

OCR 服务错误码 (AIS.*)

| 错误码 | 说明 | 解决方案 | |-------|------|---------| | AIS.0101 | 输入参数不符合规范 | 检查 image 和 url 参数是否二选一 | | AIS.0102 | 图片格式不支持 | 检查图片格式 | | AIS.0103 | 图片尺寸不满足要求 | 检查图片尺寸 | | AIS.0104 | 图片质量差 | 检查图片类型与质量 | | AIS.0105 | 算法计算失败 | 联系华为云支持人员 |

平台错误码 (ModelArts.*)

| 错误码 | 说明 | 解决方案 | |-------|------|---------| | ModelArts.4101-4107 | Token 相关错误 | 检查 Token 是否正确 | | ModelArts.4204 | 服务未开通 | 前往文字识别控制台开通 API | | ModelArts.4703-4706 | OBS 相关错误 | 检查 OBS 地址和权限 | | ModelArts.6201 | 用户账户被冻结 | 检查账户余额并完成充值 |

APIG 错误码

| 错误码 | 说明 | 解决方案 | |-------|------|---------| | APIG.0201 | 请求超时 | 检查图片大小或网络延时 | | APIG.0301 | IAM 认证失败 | 检查 AK/SK 是否正确或 token 是否过期 | | APIG.0308 | 超出速率限制 | 参考限流解决方案 |

项目结构

mz-mcp/
├── src/
│   ├── index.ts              # 主入口文件
│   ├── types.ts              # 类型定义
│   ├── constants.ts          # 配置常量
│   ├── tools/
│   │   ├── ocr.ts            # OCR 工具实现
│   │   └── index.ts          # 工具导出
│   ├── services/
│   │   ├── huaweiClient.ts   # 华为云 OCR 客户端
│   │   └── index.ts          # 服务导出
│   └── schemas/
│       ├── ocr.ts            # Zod 验证 schemas
│       └── index.ts          # Schema 导出
├── dist/                     # 编译输出
├── package.json              # 项目配置
├── tsconfig.json             # TypeScript 配置
├── .env.example              # 环境变量模板
└── README.md                 # 本文件

脚本

| 脚本 | 说明 | |-----|------| | npm run dev | 开发模式（自动重新编译） | | npm run build | 构建项目 | | npm start | 启动生产服务器 | | npm run clean | 清理编译输出 | | npm publish | 发布到 npm |

故障排除

问题：无法连接到华为云服务

解决方案：

1. 检查网络连接
2. 尝试更换服务地域（如从 cn-east-3 改为 cn-north-4）
3. 检查防火墙设置
4. 确认华为云 OCR 服务已开通

问题：认证失败 (401)

解决方案：

1. 确认 AK 和 SK 填写正确（不要填反）
2. 检查 AK/SK 是否已过期或被禁用
3. 重新生成访问密钥
4. 确认项目 ID 正确

问题：图片格式不支持

解决方案：

1. 确认图片格式在支持列表中
2. 检查 Base64 编码是否正确（不要有额外前缀）
3. 确认图片大小不超过 10MB（建议不超过 7MB）

问题：速率限制 (429)

解决方案：

1. 减少请求频率
2. 使用快速模式（quick_mode: true）处理简单图片
3. 联系华为云提升配额

贡献

欢迎提交 Issue 和 Pull Request！

许可证

AGPL-3.0

链接

• 华为云控制台
• Model Context Protocol
• GitHub 仓库