Crunch Accounting (crunch-mcp)

---

“这个月的业务情况怎么样？” 您的两个银行账户中共有 £18,240，公司信用卡上有 £312。三张销售发票尚未付款，总计 £7,800。发给 Example Client Ltd 的 INV-0042（£2,400）已逾期 12 天；另外两张尚未到期。支出方面，9 月有四笔费用未附收据，Example Hosting Ltd 的一张账单（£96）仍未付款。需要我为 INV-0042 拟一封礼貌的催款邮件，还是列出缺少收据的费用？

用通俗的语言询问您的业务情况。助手会从 70 个工具中选择合适的工具来查询信息，并在您允许的情况下进行更改。例如：

• 🩺 “帮我检查一下业务状况。”
• 🧾 “这是去利兹的火车票收据。把它记为从公司账户支付的费用。”
• 📬 “哪些发票已逾期？为每位客户拟一封催款邮件。”
• 📊 “总结上一季度的收入和支出，并估算增值税。”
• 🔍 “今年哪些费用没有附收据？”
• 📝 “按每天 £450 的价格，为 Example Client Ltd 开具 5 天咨询服务的发票，付款期限为 30 天。”

亮点

• 🐳 以 Docker 为先，体积小巧。 一个镜像（ghcr.io/mattoddie/crunch-mcp），支持 linux/amd64 和 linux/arm64，大小约为 21 MB。它是在 distroless 基础镜像上运行的单个 Go 静态二进制文件，没有 shell 或软件包管理器，并以非 root 用户身份运行。它可以为长期运行的服务提供 Streamable HTTP，也可以通过 docker run -i 使用 stdio。你也可以单独运行该二进制文件。
• 🛡️ 默认安全。 除非启用写入，否则服务只读。删除操作需要启用第二个开关，向客户发送发票或付款提醒邮件则需要启用第三个开关。这些开关对请求正文和原始 API 工具同样有效，HTTP 服务也需要 bearer token。未获准使用的工具不会注册，而删除和开具发票等破坏性工具会标注出来，以便 MCP 客户端在运行前征求确认。
• 🔑 最小权限登录。 它通过 Crunch 自有的 OAuth 2.0 流程（含 PKCE）登录，并且只请求你的设置所需的权限范围。令牌不会出现在工具输出中。
• 🔄 保持登录状态。 Crunch 会轮换刷新令牌，重复使用旧令牌会导致登录失效。crunch-mcp 会在使用新令牌前将其保存，并且绝不会同时刷新多个令牌，因此重启后仍可正常工作。
• ✏️ 谨慎更新。 更改费用或发票时，会先获取当前记录，再只修改你指定的内容，因此不会意外丢失付款信息和附件。
• 🔍 预览和审计。 每个用于更改内容的工具都接受 dry_run: true，可显示它将发送的请求；对于更新，还会逐字段显示差异，且不会实际更改任何内容。CRUNCH_AUDIT_LOG 会以 JSON Lines 格式的审计日志记录每项更改。
• 🖥️ 一键安装 Claude Desktop。 每个版本都提供适用于 macOS、Windows 和 Linux 的扩展包（.mcpb），带有设置表单，无需 Docker。
• 📎 收据和 PDF。 附加收据和工时表，下载助手可读取的收据图片，并获取发票 PDF。
• 🎛️ 可调节。 只启用所需的工具集，让模型的上下文保持精简、专注。列表工具接受 search、fields 和 limit，只获取所需内容。
• 🧪 经过测试。 每次构建时，测试套件都会针对模拟的 Crunch API 和 OAuth 服务运行。

快速开始

使用 Claude Desktop？ 从最新版本下载适用于你电脑的扩展包，打开它，输入你的 Crunch 客户端 ID，然后让 Claude “登录 Crunch”。参见 Claude Desktop。以下步骤会为其他所有客户端设置 Docker 服务。

你需要 Docker、Crunch 账户、Crunch API 访问权限，以及一个 MCP 客户端，例如 Claude Code。

1. 获取 API 访问权限。 通过 Crunch 开发者文档中链接的申请表，申请访问 Crunch 公共 API。Crunch 会向你发送一个客户端 ID；如果你设置为机密客户端，还会收到客户端密钥。Crunch 没有沙盒，因此免费 Crunch 账户是试用的好选择。详情请参阅入门指南。

2. 设置服务。

mkdir crunch-mcp && cd crunch-mcp
curl -fsSLO https://raw.githubusercontent.com/mattoddie/crunch-mcp/main/compose.yaml
curl -fsSL https://raw.githubusercontent.com/mattoddie/crunch-mcp/main/example.env -o .env
# Edit .env: set CRUNCH_CLIENT_ID (and CRUNCH_CLIENT_SECRET if you have one)
# and a random MCP_AUTH_TOKEN, which the HTTP server requires (e.g. `openssl rand -hex 32`)

3. 登录 Crunch 并启动服务。

docker compose run --rm -p 127.0.0.1:8976:8976 crunch-mcp login   # open the URL it prints and click Allow
docker compose up -d

如果你的浏览器不在 Docker 主机上，点击允许后打开的页面将无法加载。没关系：从地址栏复制 URL，然后粘贴到终端中。

4. 连接你的助手。

claude mcp add --transport http crunch http://<docker-host>:8080/mcp \
  --header "Authorization: Bearer <MCP_AUTH_TOKEN>"

现在在 Claude Code 中询问 “我的业务经营得怎么样？”。

使用 Claude Desktop、VS Code、Cursor 或 Codex？请参阅连接 MCP 客户端。不想运行服务？可以使用 docker run -i 搭配 stdio 模式，或使用本地二进制文件。

crunch-mcp 已列入官方 MCP Registry，名称为 io.github.mattoddie/crunch-mcp，因此支持从注册表安装服务的客户端可以替你完成设置，使用 stdio 模式下的 Docker 镜像或扩展包。

启用更改功能

默认情况下，助手可以查看，但不能修改。若要允许它进行更改，请将以下内容添加到 .env：

CRUNCH_ALLOW_WRITES=true    # create and update expenses, invoices, clients, suppliers, payments, attachments…
CRUNCH_ALLOW_DELETES=true   # also allow deleting records and removing payments (needs writes)
CRUNCH_ALLOW_EMAIL=true     # also allow emailing invoices and payment reminders to customers (needs writes)
CRUNCH_TOOLSETS=account,reference,expenses,invoices,clients,suppliers   # optional: expose fewer tools
CRUNCH_AUDIT_LOG=stderr     # optional: log every change (or an absolute file path; see docs/configuration.md)

登录时需要匹配的作用域，因此启用写入或删除功能后，请重新登录：

docker compose stop
docker compose run --rm -p 127.0.0.1:8976:8976 crunch-mcp login
docker compose up -d

重要操作前，先要求进行试运行：“记录这张收据，但先给我看看试运行结果。”

启用真实账簿的写入功能前，请阅读安全文档。

功能一览

工具集	涵盖内容
account	登录状态和 OAuth 登录流程、已登录用户、公司详情（增值税号和方案、地址），以及一键业务概览
reference	Crunch 所需的各类值：费用类型、增值税类型、付款方式、国家、未结会计期间、董事和员工
banking	银行账户和信用卡：余额、详情、记入账户的付款、期初余额、默认账户、归档
clients	客户（你向其开具发票的对象）：列出、查找、创建、更新和删除
suppliers	供应商：列出、查找、创建、更新、归档和删除
expenses	费用：列出和筛选、汇总、创建（含明细）、付款和收据、更新、记录和移除付款、附加和下载收据、删除
recurring	Crunch 按计划创建的定期费用：列出、创建、暂停或修改、删除
invoices	销售发票：列出和筛选、汇总、创建草稿、更新、开具、通过电子邮件发送给客户、记录和移除付款、附件、下载 PDF、删除
raw	备用入口，可调用任意 Crunch 公共 API 端点

如需查看所有工具和参数，请参阅**工具参考**。business_health_check、record_receipt 和 chase_overdue_invoices 等现成提示词会串联多个工具，处理常见任务。

文档

文档也发布在 crunch-mcp.mattoddie.dev/docs，并支持搜索。

🚀 快速入门	分步设置，从 API 访问到提出第一个问题
🔌 连接 MCP 客户端	Claude Code、Claude Desktop、VS Code、Cursor、Codex、stdio 模式
⚙️ 配置	所有环境变量、登录和令牌的工作方式、Docker secrets、工具集
🐳 部署	Compose、镜像标签、升级、TLS 反向代理、安全加固、不使用 Docker 运行
💬 使用 crunch-mcp	对话示例、提示词、变更、收据和 PDF 的工作方式
🧰 工具参考	所有工具和提示词，均从代码生成
🛡️ 安全	威胁模型、最小权限、令牌存储、安全的写入设置
📡 兼容性	Crunch API、其限制和已知差距
🩹 故障排除	常见错误及其修复方法
🛠️ 开发	架构、添加工具、测试

贡献

非常欢迎贡献，无论是错误报告、文档还是新工具。请阅读贡献指南以开始参与，并遵守行为准则。如需报告漏洞，请参阅安全政策。请勿为此公开创建 issue。

许可证

MIT © Matt Oddie

crunch-mcp 是一个独立的社区项目，与 Crunch（E-Crunch Ltd）无关联，未获其认可或赞助。“Crunch”是 E-Crunch Ltd 的商标。