MainBook Bank Statement Converter

MainBook 银行对账单转换器

专注于一项任务的金融 MCP 服务：将 PDF 银行对账单转换为经过核验的 JSON、Excel 或 CSV，而非通用会计 MCP。 执行一次 mainbook-mcp auth login 后即可在本地运行，也可以通过 MainBook 托管端点 https://mcp.mainbook.ai/mcp 使用，客户端可在该端点通过 MainBook 账户登录。 现有的 mb_live_ API 密钥仍可用于脚本和旧版客户端。

将对账单交给助手，并要求生成电子表格。PDF 会发送到 MainBook，由其提取每笔交易，将日期标准化为 YYYY-MM-DD，以精确金额保留资金数值，并重新计算对账单，确保 期初余额 + 入账 − 出账 必须与期末余额相符。不符合的行会被标记，而不会被悄悄传递。

> Convert ~/Downloads/march-statement.pdf and save the Excel next to it.

  mainbook - convert_bank_statement (MCP)
  63 transactions · 4 pages · 4 credits
  Totals reconciled against the statement
  Saved to ~/Downloads/march-statement.xlsx

Done — 63 transactions. Opening 4,127.50 and closing 3,881.05 both match
the statement, and nothing was flagged.

它不是什么

它不会连接银行账户，也不是开放银行或银行数据 API。它读取你已有的对账单文件。它不会抓取任何内容，也不会涉及银行凭据。

你需要什么

一个 MainBook 账户，以及存放对账单的文件夹。只有转换工具会消耗页面额度。其余四个工具中，get_balance 和 list_conversions 仅读取数据，get_conversion 可能会写入结果文件，而 output_folder 会更改本地偏好设置；这些工具都不会更改 MainBook 账户中的任何内容。

添加到客户端

在终端中登录一次：

uvx mainbook-mcp auth login

该命令会在浏览器中打开 MainBook，在两个位置显示相同的短代码，并等待你批准。如果已安装且可正常使用可选的 keyring 包，凭据会存储在操作系统密钥环中；否则会存储在 ~/.config/mainbook/credentials.json 中，并设置私有目录和文件权限。使用 mainbook-mcp auth status 可在服务端检查当前凭据，且不会消耗页面额度。mainbook-mcp auth logout 会先撤销已存储的密钥，再删除本地副本；如果无法连接 MainBook，它会明确说明该密钥可能仍处于有效状态。再次登录时，会先撤销之前存储的密钥，再保存新密钥。设备令牌响应不包含电子邮件或账户 ID，因此状态信息会说明未提供账户身份，而不会进行猜测。

然后在客户端的 MCP 配置中添加一条配置。Claude Desktop（Settings → Developer → Edit Config）、Claude Code 和 Cursor 使用相同的配置块；无需在其中复制密钥：

{
  "mcpServers": {
    "mainbook": {
      "command": "uvx",
      "args": ["mainbook-mcp", "~/Downloads", "~/Desktop", "~/Documents"]
    }
  }
}

Codex 使用 TOML，因此请将相同配置写入 ~/.codex/config.toml：

[mcp_servers.mainbook]
command = "uvx"
args = ["mainbook-mcp", "~/Downloads", "~/Desktop", "~/Documents"]

uvx 随 uv 一起提供；使用 brew install uv 或 curl -LsSf https://astral.sh/uv/install.sh | sh 安装一次即可。它会获取并运行已发布的包，因此无需手动下载，也无需更新。如果你不想安装 uv，可以运行 pip install mainbook-mcp，并使用相同参数设置 "command": "mainbook-mcp"——之后需要自行通过 pip install -U mainbook-mcp 升级。

文件夹参数是服务唯一可以读取对账单或写入结果的位置；任何位于这些文件夹之外的访问都会被拒绝。MAINBOOK_ALLOWED_DIRS 可通过环境变量设置相同的文件夹列表，列表使用平台的 os.pathsep 分隔（macOS/Linux 上为 :，Windows 上为 ;）。

用于脚本和 CI 的手动 API 密钥

MAINBOOK_API_KEY 的优先级高于任何已存储的登录凭据。在无法使用交互式浏览器的自动化场景中，请继续使用手动方式。若此变量会覆盖新存储的凭据，auth login 会发出警告：

export MAINBOOK_API_KEY="mb_live_REPLACE_ME"
mainbook-mcp

请在 https://mainbook.ai/developer 创建和撤销手动密钥。切勿将其提交到代码库。

Claude Desktop，无需修改配置文件

Claude Desktop 也支持单文件安装包：选择 Extensions → Install Extension…，然后选取 mainbook.mcpb。它会在对话框中询问 API 密钥和文件夹，并管理自己的 Python 运行时，因此无需事先安装任何内容。上方的配置块也能完成同样的工作；如果你已经在其中配置了其他服务，它会更合适。使用此目录构建安装包：

npx --yes @anthropic-ai/[email protected] validate manifest.json
npx --yes @anthropic-ai/[email protected] pack . dist/mainbook.mcpb

提供的功能

• convert_bank_statement：创建一个按页计费的任务，上传一个 PDF，启动转换，轮询 30-900 秒，然后返回审核后的结果。JSON 会直接内嵌返回。在本地 stdio 模式下，XLSX/CSV 字节会写入磁盘，只有完整路径会进入模型上下文。
• get_conversion：在超时后检查任务，并直接内嵌返回 JSON，或将 XLSX/CSV 写入指定的本地目标位置。
• list_conversions：返回一页账户任务游标结果，以及 next_cursor。
• get_balance：返回总积分、预留积分和可用积分，单位均为 PDF 页数。
• output_folder：读取或更改默认的本地结果文件夹。

本地 stdio 模式会列出全部五个工具。托管 HTTP 模式只会列出前四个；远程不会公布 output_folder，因为服务端的磁盘不属于客户端。

没有用于购买积分、付款、删除任务或更改账户数据的工具。能够创建转换任务、写入本地结果文件或更改输出偏好设置的工具会标记为非只读。在托管 HTTP 模式下，get_conversion 是只读的，因为它不会写入文件；在本地 stdio 模式下，它是非只读的，因为它可能会写入 XLSX 或 CSV。由于不会替换现有结果文件，因此没有任何工具会标记为破坏性操作。

结果文件的保存位置

对于本地 stdio 客户端（Claude Desktop、Claude Code、Cursor 和 Codex），XLSX 和 CSV 结果会按以下顺序写入第一个可用的目标位置：

1. 传递给 convert_bank_statement 或 get_conversion 的 output_path（绝对文件名或现有文件夹）；
2. output_folder 记住的文件夹；
3. 源 PDF 所在文件夹，使用相同的基本文件名和结果扩展名。

get_conversion 无法推断原始 PDF 所在的文件夹。若未提供 output_path，也没有有效的记忆文件夹，它会返回明确的错误，而不会猜测目标位置。每个成功的文件响应都会包含绝对路径，并说明采用了哪条规则来选择该位置。绝不会替换现有文件：statement.xlsx 后续会命名为 statement (2).xlsx，然后是 (3)，依此类推。

让客户端不带参数调用 output_folder，即可查看当前设置和所有允许的文件夹。你可以将其设为允许的绝对路径，或传入 next_to_source 以恢复默认设置。同一台计算机上的本地客户端会在 ~/.mainbook/preferences.json 中共享此偏好设置。如果已保存的文件夹不存在或不再允许使用，则会忽略该设置，并在结果中说明回退情况。

JSON 始终会直接内嵌返回。只有在明确提供 output_path 时，JSON 才会同时写入 .json 文件。在远程 HTTP 模式下，本地路径和 output_folder 不可用，因为服务端的磁盘不属于客户端。通过 OAuth 登录时，XLSX/CSV 会以一次性下载链接的形式返回，该链接会在十分钟后过期；使用旧版 mb_live_ 密钥进行身份验证时，则会返回 REST 下载说明。

手动安装要求

• Python 3.11 或更高版本
• MainBook 账户

在此目录中：

python3 -m venv .venv
.venv/bin/python -m pip install .

要优先使用操作系统密钥环，而不是私有 JSON 后备方案，请在运行登录命令或本地服务的每个环境中安装可选扩展：

.venv/bin/python -m pip install '.[keyring]'

请使用普通安装，而不要运行 pip install -e .。在此检出版本中，可编辑安装会写入一个 .pth 文件，但解释器不会加载它，因此即使软件包看起来已安装，运行 python -m mainbook_mcp 仍会失败并提示 "No module named mainbook_mcp"。另一个名称相同的文件却会被识别；文件内容没有问题，原因仍未查明。普通安装可以完全避开此问题。

如果使用手动方式进行自动化，请将 mb_live_... 值保存在机密环境或客户端配置中。切勿提交这些值。

Streamable HTTP 模式

MainBook 会在 https://mcp.mainbook.ai/mcp 为你运行此服务，因此，支持远程 MCP 的客户端无需安装任何内容。将该 URL 粘贴到 claude.ai、Claude Desktop、ChatGPT 或 Cursor 中，并在客户端提示时使用你的 MainBook 账户登录；配置中不会复制密钥。Cursor 使用固定客户端 ID，而不是自行注册，因此请提供此配置块：

{
  "mcpServers": {
    "mainbook": {
      "url": "https://mcp.mainbook.ai/mcp",
      "auth": {
        "CLIENT_ID": "mainbook-cursor",
        "scopes": ["mainbook:read", "mainbook:convert"]
      }
    }
  }
}

无法登录的客户端仍可使用来自 mainbook.ai/developer 的旧版密钥：

Authorization: Bearer mb_live_REPLACE_ME

每个请求都会读取相应凭据，因此客户端的每位用户都会访问自己的 MainBook 账户，并使用自己的页面额度。initialize 和 tools/list 无需凭据即可响应；每次工具调用都需要凭据。HTTP 模式下不存在本地文件路径和 output_folder；请传递 file_url，而不是 file_path，因为服务端的磁盘不属于你。对于 OAuth 会话，XLSX 或 CSV 结果会以一次性下载链接的形式返回（有效期 10 分钟，且只能使用一次）；对于旧版 mb_live_ 密钥，则会返回 REST 下载说明。

你也可以自行运行相同的远程模式。它是无状态的 Streamable HTTP，使用 JSON 响应：

mainbook-mcp --transport http --host 127.0.0.1 --port 8000

MCP 端点将是 http://127.0.0.1:8000/mcp。每个客户端都应发送自己的请求头：

Authorization: Bearer mb_live_REPLACE_ME

每次工具调用请求都会读取该请求头，且绝不会将其存储在全局状态中。托管 HTTP 模式不会检查 MAINBOOK_API_KEY、操作系统密钥环或本地凭据文件。对于 Codex 远程模式：

[mcp_servers.mainbook]
url = "https://mcp.mainbook.ai/mcp"
bearer_token_env_var = "MAINBOOK_API_KEY"
tool_timeout_sec = 920
default_tools_approval_mode = "writes"

如果自行部署，请将 URL 替换为你自己的主机；可自托管的部署仍需进行常规 HTTPS 终止并设置访问控制。

托管服务上的 OAuth

账户登录已在 https://mcp.mainbook.ai/mcp 启用（自 2026-08-20 起）。此源代码树中的验证器默认处于禁用状态，因此你自行运行的部署必须主动启用它。无论在哪里启用，initialize 和 tools/list 仍保持公开，而每次工具调用都可接受现有的 mb_live_ 密钥或 MainBook RS256 访问令牌。OAuth 令牌仅根据已配置的 MainBook JWKS URL 在本地验证；它们绝不会转发到 Developer API。MCP 服务会为每个内部 REST 请求另行发送一个有效期为 60 秒的 X-MainBook-Service 凭据。

托管工具的作用域由单一映射固定：convert_bank_statement 需要 mainbook:convert；get_balance、get_conversion 和 list_conversions 需要 mainbook:read。仅在启用该标志时，才会在 /.well-known/oauth-protected-resource/mcp 发布受保护资源元数据。

环境变量

• MAINBOOK_API_KEY：在 stdio 模式下可选，且优先于已存储的登录信息；在 HTTP 模式下会被忽略，因为每次工具调用都必须携带自己的 Bearer 标头。
• MAINBOOK_API_BASE_URL：REST 主机，默认为 https://api.mainbook.ai。服务会附加 /api/v1/developer。
• MAINBOOK_ALLOWED_DIRS：允许读取源文件和写入结果的本地文件夹，使用平台的 os.pathsep 分隔（macOS/Linux 上为 :，Windows 上为 ;）。位置参数中的目录优先。如果两者均未提供，则默认使用 ~/Downloads、~/Desktop 和 ~/Documents。
• MAINBOOK_MCP_TRANSPORT：stdio（默认）或 http。
• MAINBOOK_MCP_HOST：HTTP 绑定主机，默认为 127.0.0.1。
• MAINBOOK_MCP_PORT：HTTP 绑定端口，默认为 8000。
• MAINBOOK_MCP_OAUTH_ENABLED：托管 OAuth 验证器功能开关，默认为 false。关闭此开关时，不会提供元数据，托管的 Bearer 处理仍采用旧版 mb_live_ 行为。
• MAINBOOK_MCP_OAUTH_ISSUER：确切的受信任颁发者，默认为 https://api.mainbook.ai。
• MAINBOOK_MCP_OAUTH_JWKS_URL：受信任的 JWKS URL，默认为 https://api.mainbook.ai/.well-known/jwks.json。令牌标头中的 URL 会被忽略。
• MAINBOOK_MCP_OAUTH_RESOURCE：确切的受众/资源，默认为 https://mcp.mainbook.ai/mcp。
• MAINBOOK_MCP_OAUTH_CLOCK_SKEW_SECONDS：NumericDate 时钟容差，默认为 5。
• MAINBOOK_MCP_OAUTH_MAX_TOKEN_AGE_SECONDS：从 iat 起允许的最大时长，默认为 600。
• MAINBOOK_MCP_OAUTH_JWKS_CACHE_TTL_SECONDS：JWKS 缓存有效期，默认为 300。
• MAINBOOK_MCP_OAUTH_JWKS_REFRESH_MIN_INTERVAL_SECONDS：两次未知 kid 刷新尝试之间的最小间隔，默认为 30。
• MCP_SERVICE_SIGNING_SECRETS：以逗号分隔的服务门密钥。MCP 使用第一个密钥签名； Django 在轮换期间可以接受当前值和先前值。启用 OAuth 时必需；切勿提交此变量。

文件和网络安全

• file_path 和 file_url 不能同时使用。file_path 仅在本地 stdio 模式下接受；HTTP 模式会在文件系统加载器运行前拒绝它，并要求使用 file_url。
• 本地 file_path 访问和结果文件写入使用相同的配置目录。命令行位置参数中的目录优先级高于 MAINBOOK_ALLOWED_DIRS；环境变量优先级高于默认目录 ~/Downloads、~/Desktop 和 ~/Documents。每个根目录都会展开并解析，不存在的 根目录会被忽略，服务器启动时会将当前启用的根目录打印到 stderr。如果没有 剩余根目录，本地访问将默认拒绝，但服务器会继续运行。
• 写入前会解析输出文件的父目录，并通过目录身份进行检查，因此符号链接无法 将结果重定向到允许目录之外。结果文件采用独占且防冲突的方式创建； 不会覆盖已有文件。
• ~/.mainbook/preferences.json 会以原子方式替换。.mainbook 目录的权限为 0700， 偏好设置文件的权限为 0600；格式错误或无法读取的偏好设置会被安全地忽略。
• 如果可选软件包可用，终端凭据会使用操作系统密钥环。回退文件 ~/.config/mainbook/credentials.json 会在权限为 0700 的目录中以原子方式替换， 文件权限为 0600；其顶层条目以 API 基础 URL 为键。
• 本地路径会先展开并严格解析，再进行允许列表检查，因此 .. 和符号链接 无法让允许目录之外的目标看起来位于允许目录之内。解析后的路径必须严格位于某个根目录下， 不能与根目录本身相同。
• 本地文件只会打开一次。服务器使用该文件描述符执行 fstat，以确认文件为普通 文件并实施 50 MiB 上限，然后通过同一文件描述符进行有界读取。 这消除了检查与读取之间被替换的窗口，但无法完全消除解析路径和打开文件之间的竞态； 路径仍可能在这段时间内被替换。
• 本地文件必须在前 1024 字节内包含 %PDF-，之后才会调用 pypdf。不会根据文件名 扩展名判断文件是否为 PDF。
• 远程文件必须使用 HTTPS。不会跟随重定向。
• 如果 DNS 返回的任何 IPv4 或 IPv6 地址属于私有、回环、链路本地、元数据、保留或 其他非公开地址，则会拒绝这些 DNS 响应。
• URL 下载会连接到已验证的数字 IP，同时保留原始主机名用于 TLS 证书验证和 HTTP Host 标头，从而避免 DNS 重绑定竞态。
• Content-Length 和实际流式传输的字节数分别受 50 MiB 上限约束。
• PDF 会通过 pypdf 在本地解析，页数上限为 500 页。
• MainBook 提供的预签名上传标头会原样转发；MainBook Bearer 密钥绝不会 发送到存储服务。

开发检查

.venv/bin/python -m pip install '.[dev]'
.venv/bin/pytest
.venv/bin/pytest --cov=mainbook_mcp --cov-report=term-missing --cov-report=annotate:cov_annotate
.venv/bin/ruff check .

所有 REST 测试都使用模拟对象或本地桩。没有测试需要或接受真实的 MainBook API 密钥。