bookie

bookie

一款 MCP 服务，帮助自由职业者和房东记账——通过 Claude 或 GPT 操作，而非 QuickBooks。

让你的大模型导入银行对账单、对支出分类、核对整个月的账目，或生成 Schedule C。Bookie 在底层提供正确的复式记账分类账，让模型依据真实数字进行推理，而不是临时拼凑电子表格。

**适合你，如果：**你是个体经营者、自由职业者或出租房业主，已经在使用 Claude 或 GPT，愿意花 5 分钟完成设置，并且希望账目真正准确。

**不适合你，如果：**你需要仪表盘界面、多用户访问，或者对 QuickBooks／电子表格已经很满意。

开始前的准备

• Node ≥ 24
• neonctl — npm install -g neonctl（需要免费的 Neon 账户；用于数据库）
• **支持 MCP 的宿主：**Claude Desktop、Claude.ai、Cursor、VS Code，或任何支持 MCP stdio 或 HTTP 传输的宿主

快速开始（本地，stdio）

推荐方式——从源代码开始，全自动完成：

git clone https://github.com/yuens1002/bookie
cd bookie
npm install
npm run setup   # creates Neon DB, generates secrets, writes .env, runs db:push
npm run build

npm run setup 会打开浏览器以登录 Neon；如果你是 Neon 新用户，请使用“Sign up for an account”链接，并选择 GitHub／Google／Microsoft，而不是邮箱和密码——这样可以在同一轮浏览器操作中完成，无需经历可能会在 CLI 等待期间造成中断的邮箱验证。

npm run setup 会在最后打印一段可直接粘贴的 Claude Desktop 配置：

{
  "mcpServers": {
    "bookie": {
      "command": "node",
      "args": ["/absolute/path/to/bookie/dist/index.js"],
      "env": {
        "BOOKIE_DB_URL": "<printed by setup>",
        "BOOKIE_DB_DIRECT_URL": "<printed by setup>",
        "BOOKIE_API_KEY": "<printed by setup>"
      }
    }
  }
}

**在另一台机器上使用同一账本——无需克隆：**stdio 是一个本地进程——每台运行 stdio MCP 客户端的机器都会各自启动一份服务副本，因此通常每台机器都需要单独检出代码。Neon 数据库配置完成后（在任意一台机器上运行上述 npm run setup），其他每台机器只需使用相同的连接字符串即可——无需 git clone、npm install 或 npm run build 来保持同步。让那台机器上的 MCP 宿主改用已发布的软件包即可：

{
  "mcpServers": {
    "bookie": {
      "command": "npx",
      "args": ["-y", "bookie-mcp"],
      "env": {
        "BOOKIE_DB_URL": "<same value as your first machine>",
        "BOOKIE_DB_DIRECT_URL": "<same value as your first machine>",
        "BOOKIE_API_KEY": "<same value as your first machine>"
      }
    }
  }
}

npx 会按需获取并运行已发布的版本——所有使用相同 BOOKIE_DB_URL 的机器共享同一本账簿，除最初那台机器外，其他机器都无需检出代码。

**完全不克隆代码，直接初始化数据库：**如果你还没有从任何机器获取连接字符串（例如，你是手动创建 Neon 项目，而不是通过 npm run setup 创建的），可以直接推送 bookie 内置的架构：

mkdir bookie-mcp && cd bookie-mcp
npm install bookie-mcp
BOOKIE_DB_URL=<pooled> BOOKIE_DB_DIRECT_URL=<direct> npx prisma db push --schema=node_modules/bookie-mcp/prisma/schema.prisma

然后使用上文相同的 npx -y bookie-mcp 配置。

快速开始（远程，HTTP——适用于 Claude.ai 移动端）

一键部署到 Railway：

Railway 会从 GHCR 拉取预构建镜像——无需构建源代码。按提示设置必需的环境变量。完整操作指南（环境变量参考、Neon 和 Resend 设置、Claude.ai OAuth 连接器）请参阅 docs/DEPLOYING.md。

为什么没有 UI？

宿主大模型已经能读取 CSV、查看收据图片并撰写文本。Bookie 负责处理那些大模型不应该临时编造的内容：正确的复式记账分类账、以整数分为单位的货币计算、确定性的分类规则，以及可复现的报告。模型负责语言和视觉；服务负责账目。

工具

完整且始终保持最新的工具参考文档位于 docs/TOOLS.md（使用 npm run docs:tools 重新生成）。目前包括：

工具	功能
manage_accounts	创建/列出/归档账户（分段范围的类别带有税务项目）
add_transaction	记录一笔平衡的复式记账分录（资金从 → 流向）
split_transaction	一笔付款分录 + N 个类别分录（将一张收据拆分到多个类别）
import_transactions	将银行/信用卡 CSV 导入为平衡分录 — 预览 → 确认，并进行重复项去重
manage_rules	创建/列出/删除/测试/建议自动分类规则（分类 → 账户/房产，或排除），为导入预览提供建议；action=suggest 会扫描过往分类，并为出现 2 次或以上的描述返回候选规则
categorize_transaction	重新分类现有分录中的收入/支出分录 — 指定账户或应用已存储的规则
reconcile	将银行/信用卡对账单 CSV 与分类账匹配，并将过账标记为已结清 — 先预览，再提交
manage_receipts	附加、列出、删除收据数据，或获取签名下载 URL；也可选择将原始文件（JPEG、PNG、WEBP、HEIC 或 PDF）上传到 Railway Bucket 存储
generate_report	月度对账摘要，或财政年度 Schedule C / Schedule E 税务损益表
export_report	将任意报告呈现为 markdown 或 CSV
send_report	生成报告并通过 Resend 发送邮件
query_transactions	按日期范围/账户列出分录及过账
account_balances	各账户的当前余额

资源

Bookie 提供两个 MCP 资源，大模型无需调用工具即可读取：

资源 URI	MIME 类型	内容
bookie://accounts	application/json	所有活跃账户及其当前余额
bookie://reports/{year}	text/markdown	年度财政概览：Schedule C、Schedule E，以及按月汇总的单行摘要（期初余额、净收入、已结清过账数量）

提示词

三个预设工作流提示词可引导大模型完成常见记账任务：

提示词	参数	用途
monthly-close	year、month	按步骤完成月末结账：导入 CSV → 分类 → 对账 → 报告 →（可选）发送邮件
categorize-uncategorized	(无)	查找没有收入/支出分录的日记账分录，并逐一引导完成分类
prepare-tax-summary	year	生成 Schedule C + E，将其导出为 markdown 和 CSV，并可选择发送邮件

配置

完整参考请参阅 .env.example。关键变量：

变量	用途
BOOKIE_TRANSPORT	stdio（默认）或 http
BOOKIE_DB_URL	Neon 池化连接字符串
BOOKIE_DB_DIRECT_URL	Neon 直连字符串（用于 db push）
BOOKIE_API_KEY	静态 Bearer 令牌（Claude Desktop / 直连 API）
PUBLIC_URL	已部署服务的公开 HTTPS 基础 URL（Claude.ai 连接器）
JWT_SECRET	OAuth JWT 访问令牌的 HS256 签名密钥
OAUTH_CLIENT_ID	OAuth 客户端 ID（默认：claude-ai-connector）
OAUTH_CLIENT_SECRET	使用 OAuth 时必填：未设置时，/authorize 会拒绝所有请求（防止任何访客获得授权）；/token 也会验证此值。请在 Claude.ai 连接器设置中输入此值。
RESEND_API_KEY	send_report 使用的 Resend API 密钥
RESEND_FROM	send_report 使用的已验证发件人地址（例如：Bookie <[email protected]>）
AWS_ENDPOINT_URL / AWS_S3_BUCKET_NAME / AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY / AWS_DEFAULT_REGION	Railway Bucket 凭据 — 将存储桶连接到服务时会自动注入（使用 AWS SDK Generic 样式）；启用 manage_receipts 中的收据文件上传

文档

• 架构 — 数据模型、传输方式、分层
• 部署 — Railway + Neon + Resend 设置
• 路线图 — 分阶段计划
• 变更日志 — 已发布内容
• 发布 — 版本管理 + 发布流程
• 工具 — 自动生成的手册
• 贡献 — 设置、规范、测试

安全

Bookie 会将财务数据存储在你的 Neon Postgres 数据库中；连接字符串保存在 .env（已加入 gitignore）和 Railway 环境变量中，切勿提交。HTTP 传输要求每个 /mcp 请求都进行身份验证：使用静态 Bearer 令牌（BOOKIE_API_KEY），或使用由 /token 端点颁发的 OAuth JWT。在服务器暴露到 localhost 以外之前，请至少设置一种身份验证方式。完整的 Claude.ai 连接器 OAuth 设置说明，请参阅 docs/DEPLOYING.md。

许可证

MIT