基于MCP协议与OCR的智能票据识别工具开发实践

1. 项目概述：一个基于MCP协议的智能票据转换工具

最近在折腾一些自动化工作流，经常需要处理各种格式的票据和收据，比如PDF、图片、邮件附件等等。手动录入数据不仅耗时，还容易出错。就在我寻找解决方案的时候，发现了cheatbased/receiptconverter-mcp这个项目。光看名字，receiptconverter是票据转换器，MCP是关键后缀，这立刻让我意识到，这绝不是一个简单的格式转换脚本，而是一个基于Model Context Protocol的、能与AI智能体深度集成的工具。

简单来说，这个项目旨在解决一个非常具体的痛点：如何让AI助手（比如Claude、Cursor等）理解并处理我们日常收到的各种非结构化票据文件。它通过MCP协议，将票据文件（图像、PDF）中的关键信息（如商户名称、日期、金额、税项、商品明细）提取出来，并转换成结构化数据（如JSON），从而让AI能够“读懂”票据内容，并在此基础上进行汇总、分析、记账或生成报告。

想象一下，你只需要把一堆餐饮发票、差旅报销单、网购订单截图扔给AI，它就能自动帮你整理出月度消费报告、生成报销单、甚至分析消费习惯。receiptconverter-mcp就是实现这个场景的“桥梁”和“翻译官”。它非常适合开发者、财务自动化爱好者、以及任何希望将琐碎的票据处理工作交给AI来完成的个人或团队。接下来，我就结合自己的实践，深入拆解这个项目的设计思路、核心实现以及如何将它集成到你的AI工作流中。

2. 核心架构与MCP协议解析

2.1 为什么是MCP？协议的核心价值

在深入代码之前，必须先理解MCP。Model Context Protocol 是由Anthropic提出的一种开放协议，用于标准化AI应用程序（客户端，如Claude Desktop、Cursor）与外部工具、数据源（服务器）之间的通信。你可以把它想象成AI世界的“USB标准”或“插件接口规范”。

在receiptconverter-mcp的语境下：

• MCP服务器：就是这个票据转换工具本身。它封装了票据识别、信息提取的核心能力。
• MCP客户端：就是你使用的AI应用，比如配置了MCP的Claude Desktop。
• 协议作用：客户端通过标准化的方式“发现”服务器提供了哪些“工具”（Tools），然后可以调用这些工具来处理用户提供的票据文件。

这种架构带来了几个关键优势：

1. 解耦与标准化：AI应用无需内置复杂的OCR（光学字符识别）和票据解析逻辑，只需遵循MCP协议就能调用外部专业服务。同样，receiptconverter可以服务任何兼容MCP的客户端，无需为每个客户端单独开发适配器。
2. 上下文安全：票据可能包含敏感信息。MCP协议允许工具在本地运行，数据无需上传至第三方AI服务商，保障了隐私和安全。这对于处理商业发票或个人信息至关重要。
3. 能力扩展：开发者可以轻松地为AI助手增加新的、强大的专业能力，而无需等待AI模型本身去学习和集成这些功能。

cheatbased/receiptconverter-mcp项目正是实践这一理念的典范。它将自己实现为一个MCP服务器，对外提供诸如extract_receipt或parse_receipt_image这样的标准化工具。当你在Claude中上传一张发票图片并询问“这张发票的总金额是多少？”时，Claude（客户端）会自动调用本地的receiptconverter-mcp服务器提供的工具来解析图片，然后将结构化的结果作为上下文，再生成回答。

2.2 项目技术栈与模块拆解

浏览项目代码，可以清晰地看到其技术选型围绕着“文件处理”、“OCR识别”、“结构化提取”和“MCP服务”四个核心环节。

1. 文件预处理模块：

   • 支持格式：通常包括jpg,jpeg,png,pdf。对于PDF文件，需要先将其转换为图像，才能进行OCR。这里可能会用到PyPDF2或pdf2image库，配合poppler工具。
   • 图像优化：在OCR前，对图像进行预处理是提高识别率的关键。常见的操作包括：灰度化、二值化、降噪、透视校正（纠正拍摄倾斜）和锐化。项目可能会使用OpenCV或PIL(Pillow) 库来实现这些功能。
   • 注意事项：从PDF转换图像时，需要设置合适的DPI（如300），在清晰度和处理速度间取得平衡。对于多页PDF，需要逐页处理。

2. OCR核心引擎：

   • 选型分析：目前主流的选择是Tesseract和EasyOCR。Tesseract是老牌开源引擎，准确度高，但对复杂版面和非理想图片的适应性稍弱。EasyOCR基于深度学习，对自然场景下的文字、多语言混合识别效果更好，且内置了文本检测模型。
   • 本项目倾向：考虑到票据格式多样、拍摄角度不定，receiptconverter-mcp极有可能选用EasyOCR或结合两者使用。它在项目依赖（requirements.txt或pyproject.toml）中会明确体现。
   • 实操心得：EasyOCR使用虽然简单，但第一次运行时会自动下载识别模型，需要保证网络通畅。模型文件较大，需注意磁盘空间。可以指定gpu=False在CPU上运行，但速度会慢很多。

3. 信息提取与结构化模块：

   • 这是项目的“大脑”。OCR只给出了文本和位置，而我们需要的是语义信息。
   • 基于规则的提取：对于格式相对固定的票据（如某连锁超市的小票），可以通过正则表达式匹配“总计”、“合计”、“Total”等关键词后的数字金额，匹配日期格式来找到交易日期。
   • 基于机器学习/深度学习的提取：对于格式千变万化的票据，更鲁棒的方法是使用预训练模型进行命名实体识别（NER），识别出“商户名”、“日期”、“金额”、“税号”等实体。项目可能会集成像spaCy的金融票据NER模型，或者使用如LayoutLM这类文档智能模型。
   • 后处理与验证：提取出的金额需要统一货币单位，日期需要解析为标准格式（如ISO 8601）。还需要设计一些启发式规则来校验数据的合理性，例如总金额应等于各项明细金额之和（含税）。

4. MCP服务器封装模块：

   • 这是项目作为MCP工具的“外壳”。它会使用MCP的SDK（如mcpPython库）来创建一个服务器。
   • 核心是定义工具（Tools）：服务器会声明一个或多个工具，例如：

     @mcp.tool() async def extract_receipt(file_path: str) -> dict: """从给定的图像或PDF文件路径中提取票据信息。""" # 调用上述预处理、OCR、提取模块的逻辑 processed_image = preprocess(file_path) ocr_text = run_easyocr(processed_image) structured_data = parse_receipt_info(ocr_text) return structured_data

   • 资源（Resources）：除了工具，MCP服务器还可以提供“资源”，例如一个实时更新的、已解析票据的列表视图。这允许AI客户端动态获取上下文。

5. 输出与集成：

   • 最终输出是一个结构化的字典或JSON对象，例如：

     { "merchant": "XX咖啡馆", "date": "2023-10-27", "total_amount": 65.50, "currency": "CNY", "tax": 3.25, "items": [ {"name": "美式咖啡", "quantity": 2, "unit_price": 15.00}, {"name": "芝士蛋糕", "quantity": 1, "unit_price": 35.50} ] }

   • 这个JSON会被MCP客户端接收，并作为对话上下文的一部分，AI便可以基于这些准确的数据进行后续分析和对话。

3. 从零开始部署与集成实战

3.1 本地开发环境搭建

假设我们是在一个干净的Python环境中开始。我强烈建议使用uv或poetry进行包管理和虚拟环境控制，它们比传统的venv+pip更高效、更现代。

步骤一：获取项目代码

# 使用 git 克隆项目 git clone https://github.com/cheatbased/receiptconverter-mcp.git cd receiptconverter-mcp # 如果你使用 uv (推荐) uv sync # 这会自动创建虚拟环境并安装所有依赖 # 如果你使用 poetry poetry install # 传统方式 python -m venv .venv source .venv/bin/activate # Linux/Mac # .venv\Scripts\activate # Windows pip install -r requirements.txt

注意：安装过程可能会因为需要编译某些计算机视觉库（如opencv-python、easyocr的依赖）而耗时较长，请保持网络连接。如果遇到问题，通常是缺少系统级依赖（如libgl1-mesa-glx在Linux上），需要根据错误提示单独安装。

步骤二：验证核心依赖安装完成后，可以写一个简单的测试脚本，验证OCR引擎是否能正常工作：

# test_ocr.py import easyocr reader = easyocr.Reader(['ch_sim', 'en']) # 指定中文简体和英文 result = reader.readtext('test_receipt.jpg', detail=0) # detail=0只返回文本 print(result[:3]) # 打印识别出的前三条文本

运行这个脚本，如果它能成功导入并打印出一些文本（即使不准确），说明OCR环境基本就绪。

3.2 配置MCP客户端（以Claude Desktop为例）

要让receiptconverter-mcp真正发挥作用，必须将其配置到你的AI助手客户端中。这里以最流行的Claude Desktop为例。

1. 定位Claude配置目录：

   • macOS:~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows:%APPDATA%\Claude\claude_desktop_config.json
   • Linux:~/.config/Claude/claude_desktop_config.json

2. 编辑MCP服务器配置： 打开（或创建）上述配置文件，添加一个mcpServers字段。你需要指定服务器的启动命令。假设你的项目在/path/to/receiptconverter-mcp。

   { "mcpServers": { "receipt-converter": { "command": "/path/to/your/venv/bin/python", "args": [ "/path/to/receiptconverter-mcp/server.py" ], "env": { "PYTHONPATH": "/path/to/receiptconverter-mcp" } } } }

   • command: 是你Python虚拟环境中python解释器的绝对路径。
   • args: 是启动MCP服务器的脚本文件，通常是项目根目录下的server.py或main.py。
   • env: 确保Python能正确找到项目模块。

3. 重启与验证：

   • 保存配置文件并完全重启Claude Desktop。
   • 打开Claude，新建一个对话。如果配置成功，你通常可以在输入框附近看到一个“工具”或“插件”的图标，点击可能能看到可用的工具列表。或者，你可以直接尝试输入：“我上传了一张发票图片，你能用票据转换工具帮我分析一下吗？”
   • Claude应该会识别到可用的extract_receipt工具，并可能自动调用它来处理你上传的图片附件。

实操心得：配置MCP服务器时，90%的问题都出在路径和命令上。务必使用绝对路径。Windows用户尤其要注意路径中的反斜杠\需要转义或使用正斜杠/。一个调试技巧是，先在终端中手动运行你配置的command和args，确保服务器能独立启动并打印出MCP初始化日志。

3.3 服务器核心逻辑实现探秘

让我们深入server.py，看看一个典型的MCP服务器是如何构建的。以下是一个高度还原的代码结构：

import asyncio from contextlib import asynccontextmanager from typing import Any, List import mcp from mcp import ClientSession, StdioServerParameters import easyocr from PIL import Image import json import re # ... 其他导入 # 1. 初始化全局资源（如OCR阅读器） reader = easyocr.Reader(['ch_sim', 'en', 'ja']) # 支持多语言 # 2. 定义工具函数 @mcp.tool() async def extract_receipt(file_uri: str) -> str: """ 从文件URI（支持data: URI或file://）中提取票据信息。 返回结构化的JSON字符串。 """ # 解析URI，获取本地文件路径或Base64数据 local_path = resolve_file_uri(file_uri) # 调用处理流水线 try: # 预处理 images = load_and_preprocess(local_path) # 处理PDF或图片 all_text = "" for img in images: # OCR识别 result = reader.readtext(img, paragraph=True) # 按段落组织 page_text = "\n".join([item[1] for item in result]) all_text += page_text + "\n---\n" # 信息提取 structured_data = parse_receipt_text(all_text) # 返回JSON return json.dumps(structured_data, ensure_ascii=False, indent=2) except Exception as e: return json.dumps({"error": f"处理失败: {str(e)}"}) # 3. 信息提取逻辑示例（规则+启发式） def parse_receipt_text(text: str) -> dict: """解析OCR文本，提取结构化信息。""" lines = text.split('\n') receipt_info = { "merchant": None, "date": None, "total": None, "currency": "CNY", # 默认货币 "items": [] } # 规则1：查找商户名（通常在开头几行） merchant_patterns = [r"^(.+?)(公司|商店|超市|餐馆|咖啡|Invoice|Receipt)", r"商户名称[:：]\s*(.+)"] for line in lines[:5]: for pattern in merchant_patterns: match = re.search(pattern, line, re.IGNORECASE) if match: receipt_info["merchant"] = match.group(1).strip() break # 规则2：查找日期 date_patterns = [ r"(\d{4}[-/年]\d{1,2}[-/月]\d{1,2}日?)", r"(\d{1,2}[-/月]\d{1,2}[-/年]\d{4})", r"Date[:：]\s*(\d{4}-\d{2}-\d{2})" ] for line in lines: for pattern in date_patterns: match = re.search(pattern, line) if match: receipt_info["date"] = match.group(1) break # 规则3：查找总金额（寻找“总计”、“合计”、“Total”等关键词后的最大数字） total_keywords = ["总计", "合计", "总额", "应收", "Total", "Amount Due", "GRAND TOTAL"] total_candidates = [] for i, line in enumerate(lines): for keyword in total_keywords: if keyword in line: # 查找该行及后续行中的金额数字 amount_line = line + " " + " ".join(lines[i:i+3]) amounts = re.findall(r'[\d,]+\.?\d{0,2}', amount_line) # 尝试解析为浮点数，并取最大值（假设总金额是最大的那个） for amt_str in amounts: try: amt = float(amt_str.replace(',', '')) total_candidates.append(amt) except ValueError: pass if total_candidates: receipt_info["total"] = max(total_candidates) # 规则4：查找商品行（这是一个更复杂的启发式规则，需要根据具体票据格式调整） # 例如，匹配“数量*单价”或带有金额的行 item_pattern = r'^(.+?)\s+(\d+)\s*[xX*]\s*([\d.]+)\s+([\d.]+)$' # 简化的模式 for line in lines: match = re.match(item_pattern, line) if match: name, qty, unit_price, total_price = match.groups() receipt_info["items"].append({ "name": name.strip(), "quantity": int(qty), "unit_price": float(unit_price), "total": float(total_price) }) return receipt_info # 4. 创建并运行MCP服务器 async def main(): # 创建服务器实例，并注册我们定义的工具 async with mcp.Server( name="receipt-converter", version="0.1.0", tools=[extract_receipt], # 可以注册多个工具 ).run_stdio() as server: # 保持服务器运行，等待客户端调用 await server.wait_closed() if __name__ == "__main__": asyncio.run(main())

这段代码勾勒出了服务器的核心骨架。关键在于@mcp.tool()装饰器，它将一个普通的异步函数声明为MCP工具。客户端（Claude）会通过标准输入输出（stdio）与这个服务器进程通信，调用extract_receipt函数并传递文件URI。

4. 高级应用与定制化开发

4.1 处理复杂票据与提升准确率

基础规则引擎对于格式规整的票据可能够用，但现实世界的票据五花八门。要提升鲁棒性，需要考虑以下策略：

1. 多模型OCR融合：

   • 不要只依赖一个OCR引擎。可以同时使用Tesseract和EasyOCR，然后对识别结果进行投票或基于置信度融合。例如，对于数字金额，如果两个引擎结果一致，可信度就极高。
   • 代码示例：

     def ocr_fusion(image_path): import pytesseract from easyocr import Reader # Tesseract tess_text = pytesseract.image_to_string(image_path, lang='chi_sim+eng') # EasyOCR easy_reader = Reader(['ch_sim','en']) easy_result = easy_reader.readtext(image_path, detail=0, paragraph=True) easy_text = '\n'.join(easy_result) # 简单的行级对齐与融合（此处为简化逻辑） # 更复杂的做法可以基于字符位置和置信度 fused_lines = [] tess_lines = tess_text.split('\n') easy_lines = easy_text.split('\n') # ... 实现一个对齐和冲突解决算法 ... return fused_text

2. 引入深度学习模型进行版面分析与实体识别：

   • 对于非常规票据，规则会失效。此时可以使用预训练的文档理解模型，如Microsoft的LayoutLM或Uber的DocFormer。这些模型能同时理解文本、位置和版面信息，直接输出结构化的实体。
   • 实现思路：将OCR得到的文本和其边界框坐标一起输入到微调过的LayoutLM模型中，模型会为每个token打上标签（如B-MERCHANT,I-DATE,B-TOTAL等）。
   • 注意事项：这类模型需要GPU才能达到实用速度，且可能需要针对中文票据进行微调以获得最佳效果。

3. 后处理与逻辑校验：

   • 金额校验：计算提取出的所有商品项金额之和，与提取出的“总金额”进行比对。如果差异在可接受范围内（如1元以内），则信任总金额；如果差异大，则可能需要重新检查商品行提取或总金额定位是否错误。
   • 日期格式化：将各种格式的日期字符串（“2023年10月27日”、“10/27/2023”、“27-10-23”）统一转换为标准日期对象或ISO格式字符串。
   • 商户名归一化：通过字符串模糊匹配（如使用fuzzywuzzy库）或查找已知商户列表，将“麦当劳（王府井店）”归一化为“麦当劳”。

4.2 扩展MCP服务器能力

一个强大的MCP服务器不应只有一个工具。我们可以根据需求扩展：

1. 添加批量处理工具：

   @mcp.tool() async def batch_extract_receipts(directory_uri: str) -> str: """处理指定目录下的所有票据文件（图片/PDF）。""" # 解析目录URI，遍历文件 # 对每个文件调用 extract_receipt 逻辑 # 汇总所有结果到一个列表中返回 pass

2. 添加票据分类工具：

   @mcp.tool() async def classify_receipt_type(file_uri: str) -> str: """识别票据类型：餐饮、交通、办公用品、差旅等。""" # 可以使用轻量级文本分类模型（如fastText）或基于关键词的规则 # 返回分类结果，便于后续按类别进行不同规则的处理或统计 pass

3. 提供资源（Resources）： MCP除了工具，还有“资源”的概念。资源是客户端可以读取的数据源。例如，我们可以提供一个资源，让AI客户端获取最近处理过的10张票据的摘要。

   @mcp.resource("receipts://recent") async def get_recent_receipts() -> str: """返回最近处理的票据摘要列表。""" # 从数据库或内存缓存中读取最近的处理记录 recent_list = cache.get('recent_receipts', []) return json.dumps(recent_list)

   这样，AI在对话中就可以引用“你最近处理过的那张咖啡厅发票”，上下文更连贯。

4.3 集成到自动化工作流

receiptconverter-mcp的终极价值在于作为自动化流水线的一环。

1. 与自动化平台（如n8n, Zapier）结合：

   • 虽然MCP原生是为AI客户端设计的，但其本质是一个标准输入输出的进程。你可以写一个简单的包装脚本，通过命令行调用这个服务器进程（模拟MCP客户端），传入文件路径，获取JSON输出。
   • 然后，在n8n中创建一个工作流：监控某个邮箱附件或网盘文件夹 -> 下载新票据 -> 调用包装脚本 -> 将输出的JSON数据存入数据库（如Airtable）或发送到记账软件（如QuickBooks）的API。

2. 构建本地REST API网关：

   • 如果你希望其他非MCP应用也能调用票据转换能力，可以构建一个简单的FastAPI应用，作为MCP服务器的网关。
   • FastAPI接收文件上传的HTTP请求，然后在后端启动或调用一个已运行的receiptconverter-mcp子进程，通过标准输入输出进行通信，获取结果后再通过HTTP响应返回。
   • 这样，任何能发送HTTP请求的应用（手机App、浏览器插件）都可以使用这个服务。

5. 常见问题、调试与优化指南

5.1 安装与配置问题排查

5.2 识别准确率优化技巧

1. 预处理是关键：

   • 方向校正：使用OpenCV的minAreaRect或HoughLines检测文本倾斜角度并进行旋转校正。
   • 光照不均：使用cv2.createCLAHE(对比度受限的自适应直方图均衡化) 来改善。
   • 阴影和污渍：尝试使用cv2.inpaint或形态学操作（开运算、闭运算）去除小噪点。
   • 代码片段示例：

     import cv2 import numpy as np def preprocess_image(image_path): img = cv2.imread(image_path) # 1. 灰度化 gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY) # 2. 二值化（自适应阈值，应对光照不均） binary = cv2.adaptiveThreshold(gray, 255, cv2.ADAPTIVE_THRESH_GAUSSIAN_C, cv2.THRESH_BINARY, 11, 2) # 3. 降噪（中值滤波） denoised = cv2.medianBlur(binary, 3) # 4. 锐化（可选） kernel = np.array([[-1,-1,-1], [-1,9,-1], [-1,-1,-1]]) sharpened = cv2.filter2D(denoised, -1, kernel) return sharpened

2. 调整OCR参数：

   • EasyOCR:reader.readtext(image, paragraph=True, batch_size=4, width_ths=0.7)。paragraph=True将相邻文本框合并为段落，更适合票据。width_ths控制文本框合并的宽度阈值。
   • Tesseract: 通过pytesseract配置PSM（页面分割模式）。对于票据，--psm 6（假设为统一的文本块）或--psm 11（稀疏文本）可能更合适。还可以通过-c设置白名单，例如只识别数字和货币符号：-c tessedit_char_whitelist=0123456789.,$¥€。

3. 领域自适应：

   • 如果你的票据主要来自某个特定领域（如医疗、餐饮），可以收集一些样本，微调一个小的文本分类或NER模型。即使只有几十张标注好的票据，用spaCy进行少量样本的增量训练，也能显著提升该领域票据的字段识别准确率。

5.3 性能与生产化考量

1. 并发处理：原生的MCP stdio服务器是单线程异步的。如果同时处理多个请求，可能会阻塞。对于高并发需求，可以考虑：

   • 使用asyncio.to_thread将耗时的OCR和解析任务放到线程池中执行，避免阻塞事件循环。
   • 或者，将MCP服务器作为前端，将实际的识别任务提交到一个后台任务队列（如Celery+Redis）中，由多个工作进程并行处理。

2. 缓存机制：同一张票据可能被多次分析。可以在工具函数开始时计算文件的MD5哈希值作为键，将识别结果缓存到内存（如functools.lru_cache）或Redis中，设置合理的过期时间。

3. 错误处理与日志：在生产环境中，必须完善错误处理。使用logging模块记录详细的处理日志，包括文件哈希、处理步骤、耗时、识别结果和遇到的异常。这便于后续排查问题和优化模型。

4. 容器化部署：使用Docker将整个环境（Python、系统依赖、模型文件）打包。这确保了环境的一致性，简化了部署流程。Dockerfile中需要安装系统依赖、下载模型，并设置正确的启动命令。

通过以上这些步骤，你不仅能将cheatbased/receiptconverter-mcp这个项目成功运行起来，更能深入理解其背后的设计哲学，并根据自己的实际需求进行定制和强化。它从一个有趣的工具，变成了一个连接物理世界票据与数字世界AI的强大枢纽，真正释放了自动化处理的潜力。