Recite MCP

recite-mcp

mcp-name: io.github.rivradev/recite-mcp

recite-mcp 是 Recite API 的 MCP 服务。它提供 Recite MCP 中完整的文档化功能，涵盖扫描、交易、导入、批处理作业、项目、摘要、Webhook、规则、用量和导出，同时保留本地账本/记忆工作流，供偏好本地优先记账的 Agent 使用。

安装

最终用户

推荐：

uvx recite-mcp

替代方案（pipx）：

pipx install recite-mcp

替代方案（pip）：

python -m pip install recite-mcp

贡献者

python -m pip install -e .[dev]
pytest -q
python -m recite_mcp.server

必需的环境变量

在 https://recite.rivra.dev/settings/api 获取 API 密钥（每月包含 30 次免费扫描），然后设置 RECITE_API_KEY（处理收据时必需；即使未设置，服务仍可启动，以便 validate_setup() 报告缺少的配置）：

# Windows PowerShell
$env:RECITE_API_KEY="re_live_xxx"

# macOS/Linux
export RECITE_API_KEY="re_live_xxx"

可选的主目录覆盖项：

# Windows PowerShell
$env:RECITE_HOME="C:\path\to\recite-home"

# macOS/Linux
export RECITE_HOME="$HOME/.config/recite"

MCP 客户端配置

复制并粘贴此配置：

{
  "mcpServers": {
    "recite": {
      "command": "uvx",
      "args": ["recite-mcp"],
      "env": {
        "RECITE_API_KEY": "re_live_xxx"
      }
    }
  }
}

如果通过 pipx 或 pip 安装，请使用：

{
  "mcpServers": {
    "recite": {
      "command": "recite-mcp",
      "args": [],
      "env": {
        "RECITE_API_KEY": "re_live_xxx"
      }
    }
  }
}

故障排查

MCP Registry 所有权验证失败

• 现象：发布到 Registry 时，返回 PyPI 所有权/README 验证错误。
• 解决方法：在打包后的 README 中保留以下原样内容：mcp-name: io.github.rivradev/recite-mcp，然后升级版本，并在发布到 Registry 前上传新的 PyPI 版本。

RECITE_API_KEY 缺失或无效

• 现象：validate_setup() 报告 missing_api_key，或 API 请求被拒绝。
• 解决方法：在 MCP 客户端的 env 配置（推荐）或 Shell 环境中设置 RECITE_API_KEY。

找不到 uvx 命令

• 现象：终端提示无法识别 uvx。
• 解决方法：先安装 uv，或使用以下替代方案之一：
  • pipx install recite-mcp
  • python -m pip install recite-mcp

安装后找不到 recite-mcp 命令

• 现象：通过 pipx/pip 安装后，提示无法识别该命令。
• 解决方法：
  • 对于 pipx：运行 pipx ensurepath，然后重新打开终端。
  • 对于 pip：使用模块入口点运行：python -m recite_mcp.server

MCP 客户端已启动，但工具不可用

• 现象：服务似乎已配置，但未列出任何工具/资源。
• 解决方法：
  • 确认 MCP 配置 JSON 有效。
  • 确认命令和参数与安装方式匹配（uvx 与 recite-mcp）。
  • 修改配置后重启 MCP 客户端。

无法从 PyPI 下载（uvx/pip）

• 现象：安装/运行因网络/代理错误而失败。
• 解决方法：确保环境可以访问 PyPI（或配置代理/自定义索引）。如果所在网络有访问限制，可能需要将 PyPI 加入允许列表，或使用内部镜像。

快速本地验证（无需 MCP 客户端）

• 运行 recite-mcp --validate（或 uvx recite-mcp --validate）以输出本地配置/健康状态 JSON。如果存在 API 密钥，退出代码为 0；否则为 1。

主要功能

API 工具（共 41 个）：

• 扫描 — scan_receipt（文件、URL、base64 或原始文本；临时模式）、get_scan
• 交易 — 创建、列出（支持筛选）、获取、更新、删除、import_transactions（JSON 列表、CSV 文本或 CSV 文件）
• 批量扫描 — submit_batch_scans（1–20 项，异步，Webhook 通知）、get_batch_scan_status、get_batch_scan_results
• 项目 — 列出、创建、更新、删除
• 汇总 — get_summary（周期、日期范围、分组方式）
• Webhook — 创建、列出、删除（transaction.created/updated/deleted、batch.completed）
• 对账 — create_reconciliation_link、list_reconciliation_links、update_reconciliation_link、delete_reconciliation_link、run_auto_match、get_reconciliation_summary、get_reconciliation_recommendations、export_reconciliation
• 规则 — 创建、列出、更新、删除（vendor_category、default_project、processing_preference）
• 类别 — get_categories（17 个内置类别及自定义类别）、create_category、delete_category
• 供应商 — get_vendors、create_vendor、delete_vendor
• 用量 — get_usage（周期、细分）
• 导出 — export_transactions（CSV/JSON，可选择保存文件）

本地工具：

• process_receipt — 一步完成扫描并追加到分类账（可选重命名、试运行、类别提示）
• process_receipts_batch — 扫描目录中的图像/PDF（递归处理、试运行预览）
• summarize_ledger、export_ledger、add_ledger_correction — 本地 CSV 分类账管理
• update_memory、list_memory — 持久化 Agent 指令存储
• get_config、validate_setup — 配置检查和运行状况检查

资源： recite://ledger、recite://memory、recite://health

文档

• 用户指南：docs/user_guide.md