★ FEATURED ARTICLE 1. 为什么要在 Cherry Studio 里把 PaddleOCR-VL 挂成 MCP 工具PaddleOCR-VL 是百度飞桨团队推出的视觉语言 OCR 模型它和传统 OCR 最大的区别在于不只是把图片里的文字抠出来还能理解版面结构、表格、公式、手写体甚至能按你的指令做结构化输出。比如你丢一张发票截图进去它能直接返回金额、开票日期、抬头这样的字段而不是一堆散乱的文字行。适合谁用做文档自动化、票据识别、知识库入库、RAG 前处理的开发者尤其是手里已经有一堆图片素材、想让大模型直接看图说话的人。但实际用起来有个绕不开的麻烦OCR 是一个能力LLM 是另一个能力。你不可能每次识别图片都手动切到某个网页上传再把结果复制回对话框。更优雅的做法是把 OCR 封装成一个工具让大模型在对话里自己决定这张图我需要调 OCR。这就是 MCPModel Context Protocol的价值——它把外部能力标准化成模型可调用的工具Cherry Studio 作为支持 MCP 的客户端正好能把 PaddleOCR-VL 接进来。我试过几种接法最省心的还是走 MCP Server 这条路Cherry Studio 负责对话和工具调度PaddleOCR-VL 的 MCP Server 负责真正调 OCR 接口。剩下的问题就是 API-Key 怎么管。如果你同时用 Claude、GPT、国产模型、OCR 服务每个平台一套 Key配置散落在各个客户端里换台机器就要重新找一遍。这篇就按TaoToken 统一 Key的思路来写把模型调用和 OCR 调用的凭证收敛到一处管理Cherry Studio 里只填一次后面加工具、换模型都不用再翻控制台。下面从环境准备讲到可复制的 JSON 配置再到一次真实的 OCR 请求验证最后把常见的 401、uvx 找不到、返回结构读不出来这些坑挨个排一遍。全程命令和参数都能直接抄。2. TaoToken 前置准备统一 Key 与 MCP 运行环境在动手改 Cherry Studio 配置之前先把两件事理清楚一是凭证从哪来二是 MCP Server 靠什么跑起来。先说凭证。PaddleOCR-VL 的 MCP Server 本质上是个本地进程它启动时会去读环境变量里的 API Key然后拿这个 Key 去请求远端的 OCR 接口。所以 Key 的存放位置决定了你后面维护的成本。如果你只接一个 OCR随便填都行但如果你还想在同一个 Cherry Studio 里接别的模型工具Key 就会越堆越多。我的做法是统一走 TaoToken 的 API Key 体系在控制台创建一把 Key模型对话、Coding Plan、以及这类工具型调用都复用它。这样 Cherry Studio 的 MCP 配置里只需要维护一个变量换机器时复制一份配置就能跑。具体操作打开 https://taotoken.net/api-keys 登录后点创建 API Key复制出来先存到本地密码管理器。注意这把 Key 只在创建时完整显示一次关掉页面就看不到了。如果你打算在多个客户端Cherry Studio、Cline、Codex里共用建议按客户端命名比如taotoken-cherry-ocr方便后面排查是哪个客户端在调。再说运行环境。PaddleOCR 官方提供的 MCP Server 是通过 Python 包分发的配置里用的是uvx这个命令来拉起。uvx是 uv 工具链的一部分作用类似npx——不用手动pip install直接按包名运行。所以你的机器上得先有 uv。检查方法uvx --version如果提示 command not found装一下# macOS / Linux curl -LsSf https://astral.sh/uv/install.sh | sh # Windows PowerShell powershell -c irm https://astral.sh/uv/install.ps1 | iex装完重开终端再跑一次uvx --version能打印版本号就说明就绪。这一步很关键因为 Cherry Studio 启动 MCP Server 时是直接调uvx的如果这个命令不在 PATH 里你会看到 MCP 一直转圈或者直接报spawn uvx ENOENT。还有一点uvx第一次运行paddleocr-mcp时会自动下载依赖包体积不小网络慢的话会卡住几十秒。建议先在终端手动跑一次预热uvx --from paddleocr-mcp paddleocr_mcp --help看到帮助信息输出说明包已经缓存到本地后面 Cherry Studio 启动就快了。这一步不需要填 Key只是验证包能拉下来。最后确认一下 Cherry Studio 版本。MCP 功能在较新的版本里才完善建议更新到官网最新稳定版。打开设置左侧能看到MCP 服务器这一项就说明版本支持。如果找不到这个入口先去升级客户端别急着改配置文件。3. 可复制配置Cherry Studio 的 MCP JSON 与参数详解这一节是全文的核心配置片段可以直接抄但每个字段的含义我会讲清楚方便你按自己的环境改。在 Cherry Studio 里进入 设置 → MCP 服务器 → 添加服务器选择从 JSON 导入或直接编辑 JSON。完整配置如下{ mcpServers: { PaddleOCR-VL-TaoToken: { type: stdio, description: PaddleOCR-VL 视觉 OCR凭证统一走 TaoToken, command: uvx, args: [ --from, paddleocr-mcp, paddleocr_mcp ], env: { PADDLEOCR_MCP_PIPELINE: PaddleOCR-VL, PADDLEOCR_MCP_PPOCR_SOURCE: qianfan, PADDLEOCR_MCP_SERVER_URL: https://qianfan.baidubce.com/v2/ocr, PADDLEOCR_MCP_QIANFAN_API_KEY: 你的TaoToken-API-Key } } } }逐字段说明。type固定stdio表示 Cherry Studio 会以子进程方式启动这个 Server通过标准输入输出通信不需要开端口。command是uvx对应上一节装好的工具。args里--from paddleocr-mcp指定包名paddleocr_mcp是要执行的入口模块这两个顺序不能反。env是重点。PADDLEOCR_MCP_PIPELINE设为PaddleOCR-VL表示用 VL 这条流水线而不是老的 PP-OCR。PADDLEOCR_MCP_PPOCR_SOURCE设为qianfan表示 OCR 能力来自千帆平台。PADDLEOCR_MCP_SERVER_URL是接口地址保持默认即可。最后一个PADDLEOCR_MCP_QIANFAN_API_KEY把值替换成你在 TaoToken 控制台创建的那把 Key。这里有个容易踩的坑Key 是明文写在 JSON 里的Cherry Studio 的配置文件通常存在用户目录下。如果你要把配置分享给别人或者提交到 Git记得先把 Key 换成占位符。更稳妥的做法是用系统环境变量但 Cherry Studio 的 MCP 配置对变量插值的支持因版本而异最省事的还是本地文件别外传。保存后回到 MCP 服务器列表找到PaddleOCR-VL-TaoToken点启用。如果配置正确状态会变成绿色或显示已连接点开能看到它暴露的工具通常是一个ocr或recognize之类的函数参数是图片 URL 或本地路径。如果状态一直是红色先看下一节的排错。再补一个多工具共存的写法。如果你还想在同一个 Cherry Studio 里接别的 MCP比如文件系统或数据库工具直接在mcpServers对象里并列加就行互不影响{ mcpServers: { PaddleOCR-VL-TaoToken: { ...: ... }, 另一个工具: { ...: ... } } }这样你的对话窗口里就能同时勾选多个工具模型会自己判断该调哪个。4. 验证请求一次真实的 OCR 识别与返回结果配置启用后别急着写复杂流程先用一张公开图片跑通链路确认通道是活的。在 Cherry Studio 新建对话模型随便选一个支持工具调用的比如 Claude 系列或国产支持 function call 的模型。在输入框下方或工具栏里找到工具选择勾上PaddleOCR-VL-TaoToken。然后输入识别图片https://pplines-online.bj.bcebos.com/deploy/official/paddleocr/pp-ocr-vl//dcce4b6d-1a12-4741-b571-bd27cb574200/input_img_0.jpg发送后你会看到对话里出现一个工具调用卡片显示正在调用 OCR 工具参数是这张图片的 URL。几秒后返回结果。正常情况下返回内容会包含识别出的文字块、版面信息VL 模型还可能给出结构化的描述。如果图片里有表格你会看到类似 Markdown 表格的输出如果是普通段落就是按行组织的文本。判断成功有三个标志一是工具调用卡片没有报错二是返回内容里确实有图片中的文字三是对话没有中断、模型能基于 OCR 结果继续回答。你可以紧接着追问一句把识别结果整理成 JSON看模型能不能在 OCR 返回的基础上做二次加工——这一步能验证 OCR 和大模型是否真的协同起来了。如果返回的是空内容或者报错先看工具调用卡片里的错误信息。常见的是 Key 无效或额度问题对应下一节的 401。如果工具压根没被调用检查是不是忘了在对话里勾选工具或者当前模型不支持 function call。再补一个本地图片的用法。MCP 工具通常也接受本地文件路径你可以把图片存到某个目录然后在对话里写识别本地图片/Users/yourname/Pictures/invoice.png注意路径要用绝对路径相对路径在不同工作目录下容易找不到。Windows 下写成C:\\Users\\...这种双反斜杠或正斜杠都行。跑通这一步之后你就可以把它接进更长的流程了比如让模型先 OCR 一批票据再把结果写进数据库或者做 RAG 时先用 OCR 把扫描件转成文本再切块入库。MCP 的好处就是这些步骤都能在对话里用自然语言串起来不用为每个环节单独写胶水代码。5. 常见报错排查401、uvx 找不到、返回结构读不出来这一节按真实遇到的报错来排每条都给定位方法和修复动作。401 Unauthorized / invalid api key。这是最高频的。工具调用卡片里会显示类似401或authentication failed。原因通常是PADDLEOCR_MCP_QIANFAN_API_KEY填错、Key 被删除、或者复制时带了空格。修复回到 TaoToken 控制台确认 Key 还在重新复制一次粘贴到 JSON 里时注意首尾不要有空格和换行。改完保存配置重启 MCP Server禁用再启用重新发一次请求。如果还报 401把 Key 单独拿出来用 curl 测一下排除是 Key 本身的问题还是配置没生效。spawn uvx ENOENT / local proxy failed。这个报错说明 Cherry Studio 找不到uvx命令。虽然你在终端里能跑但 GUI 应用启动时的 PATH 可能和终端不一样尤其是 macOS 从 Dock 启动的情况。修复先确认which uvx的绝对路径比如/Users/yourname/.local/bin/uvx然后把 JSON 里的command从uvx改成这个绝对路径。Windows 下同理用where uvx找到完整路径填进去。改完重启客户端。reading choices of undefined / 返回结构解析失败。这类错误通常不是 OCR 本身失败而是 MCP Server 拿到了非预期的响应体去读choices字段时发现是 undefined。常见诱因是接口地址写错、或者 Key 对应的服务没开通 OCR 权限。修复核对PADDLEOCR_MCP_SERVER_URL是不是https://qianfan.baidubce.com/v2/ocr一个字符都别错。然后确认你的账号在对应平台已经开通了 PaddleOCR-VL 服务。如果地址和权限都没问题把uvx手动跑一次加上调试输出看原始响应PADDLEOCR_MCP_QIANFAN_API_KEY你的Key uvx --from paddleocr-mcp paddleocr_mcp观察终端打印的请求和响应能直接看到服务端返回了什么。OAuth / token expired。如果你用的是带 OAuth 流程的凭证过期后会报这个。TaoToken 的 API Key 是长期有效的一般不会遇到但如果你混用了其他平台的临时 token记得定期换。修复就是重新生成 Key 并更新 JSON。工具列表为空 / 看不到 OCR 工具。MCP Server 连上了但没暴露工具多半是args写错导致入口模块没跑起来。核对--from paddleocr-mcp paddleocr_mcp这两段包名和模块名都不能改。另外确认PADDLEOCR_MCP_PIPELINE是PaddleOCR-VL写错会导致流水线加载失败。排查时有个通用技巧Cherry Studio 的 MCP 日志通常在设置里能打开或者看客户端的日志目录。日志里会记录 Server 的启动命令、stderr 输出比界面上的报错详细得多。遇到搞不定的先看日志再动手改配置。6. 把 OCR 接进日常工作流凭证收敛与后续扩展链路跑通之后真正省事的地方在于后续扩展。因为凭证统一在 TaoToken 管理你加新工具时不用再到处找 Key。比如你想再接一个文档解析的 MCP或者换一个模型做对话Cherry Studio 里只需要改模型选择MCP 配置原封不动。如果你打算长期在编码和 Agent 场景里用这套组合可以了解下 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite它把模型调用和工具调用的额度放在一起管适合每天都要跑 OCR LLM 流水线的人。只是想先验证模型效果的可以直接在模型对话页https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite里试不用配 MCP 也能感受 PaddleOCR-VL 的识别质量。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有针对不同客户端的配置示例Cherry Studio 之外的 Cline、Codex 也能照着改。最后留一个实用习惯每次改完 MCP 配置先用一张小图跑一次验证请求确认通道是活的再去跑批量任务。批量任务失败时先回退到单图验证能快速区分是配置问题还是数据问题。这套流程我用了几个月票据识别和文档入库的稳定性比手动上传高不少。
阅读完成 · 觉得有帮助？
