MainBook Bank Statement Converter 是一个金融领域的 MCP 服务器，其作用范围被限定为一项任务：把 PDF 银行对账单转换为经过校验的 JSON、Excel 或 CSV 文件，而不是一个通用会计 MCP。
【用途】 该服务器面向金融数据处理场景，读取你已经持有的对账单文件，将其转换为便于后续分析或存档的结构化格式。它不连接银行账户，不是 Open Banking 或银行数据 API，不抓取任何内容，也不涉及银行凭证。
【主要能力】 把 PDF 发送给 MainBook 后，服务器会提取每一笔交易，将日期统一规范化为 YYYY-MM-DD，保持金额为精确数值，并通过重新加总对账单进行校验：期初余额 + 贷方 − 借方 必须与期末余额一致。不符合该等式的行会被标记，而不是被静默传递。
【使用方式】 可以在本地运行：先执行一次 mainbook-mcp auth login，命令会在浏览器中打开 MainBook，并在两处显示相同的短代码，等待你批准。凭证会优先存储在操作系统钥匙串中（需安装可选 keyring 包且可用）；否则使用 ~/.config/mainbook/credentials.json，并设置私有目录和文件权限。也可以用 mainbook-mcp auth status 检查凭证状态而不消耗页面积分，用 mainbook-mcp auth logout 先撤销存储的密钥再删除本地副本。 也可以使用托管端点 https://mcp.mainbook.ai/mcp，客户端通过你的 MainBook 账户登录。现有 mb_live_ API 密钥对脚本和旧客户端仍然有效。
在客户端中添加配置即可连接。Claude Desktop、Claude Code 和 Cursor 使用同一个配置块，无需复制密钥。Codex 读取 TOML，配置写入 ~/.codex/config.toml。uvx 随 uv 提供，可用 brew install uv 或 curl -LsSf https://astral.sh/uv/install.sh | sh 安装一次；也可以 pip install mainbook-mcp 并自行用 pip install -U mainbook-mcp 升级。文件夹参数是服务器唯一允许读取对账单或写入结果的目录，之外的内容会被拒绝。MAINBOOK_ALLOWED_DIRS 可通过环境变量设置同样的列表，用平台对应的 os.pathsep 分隔（macOS/Linux 为 :，Windows 为 ;）。
Claude Desktop 还支持单文件包：Extensions → Install Extension… 选择 mainbook.mcpb，会在对话框中询问 API 密钥和文件夹，并自行管理 Python 运行时。
【暴露的工具】 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 不会远程公布，因为服务器磁盘不属于客户端。 没有用于购买积分、付款、删除任务或更改账户数据的工具。
【结果文件位置】 对于本地 stdio 客户端（Claude Desktop、Claude Code、Cursor 和 Codex），XLSX 和 CSV 结果会按以下顺序写入第一个可用目标：传给 convert_bank_statement 或 get_conversion 的 output_path（绝对文件名或已存在的文件夹）；output_folder 记住的文件夹；源 PDF 旁边，使用相同基础名称和结果扩展名。get_conversion 无法推断原始 PDF 文件夹，若没有 output_path 或有效的已记住文件夹，会返回明确错误而不是猜测目标。已有文件不会被替换，statement.xlsx 之后是 statement (2).xlsx，再之后是 (3)，依此类推。JSON 保持内联，仅在提供显式 output_path 时才写入 .json 文件。远程 HTTP 模式下，本地路径和 output_folder 不可用。
【适用场景与限制】 适用于已有 PDF 银行对账单、希望让 AI 助手输出电子表格或结构化数据的用户，尤其适合不需要连接银行账户、不希望提供银行凭证的工作流。需要 MainBook 账户和 Python 3.11 或更高版本。转换是唯一消耗页面积分的工具。手动 API 密钥方法适合自动化或无法进行交互式浏览器的场景，MAINBOOK_API_KEY 优先于已存储的登录凭证，密钥应保存在秘密环境或客户端配置中，切勿提交。身份验证方面，托管服务的 OAuth 登录已可用，自托管部署需自行启用 OAuth 验证器。工具作用域固定：convert_bank_statement 需要 mainbook:convert；get_balance、get_conversion 和 list_conversions 需要 mainbook:read。
文件与网络安全方面，file_path 和 file_url 互斥，file_path 仅在本地 stdio 下接受，HTTP 模式拒绝并要求 file_url。本地文件访问和结果写入使用同一组配置文件夹，按位置 CLI 目录、MAINBOOK_ALLOWED_DIRS、默认 ~/Downloads、~/Desktop、~/Documents 的优先级处理。输出父目录在写入前解析并按目录身份检查，符号链接无法把结果重定向到允许文件夹之外；结果创建为独占且防冲突，不覆盖已有文件。偏好文件原子替换，.mainbook 目录模式 0700、偏好文件模式 0600。本地路径在允许列表检查前会被严格解析，.. 和符号链接无法让外部目标看起来位于允许文件夹内，解析后的路径必须严格位于根目录之下而不能等于根本身。本地文件打开一次，用 fstat 要求为常规文件并执行 50 MiB 限制，然后通过同一描述符进行有界读取；这关闭了检查与读取之间的替换窗口，但未完全消除解析路径与打开之间的竞态。本地文件在前 1024 字节内必须包含 %PDF- 才会调用 pypdf，不使用文件扩展名判断。
【环境变量】 MAINBOOK_API_KEY：stdio 中可选且优先于已存储登录，HTTP 模式忽略。MAINBOOK_API_BASE_URL：REST 主机，默认 https://api.mainbook.ai，服务器追加 /api/v1/developer。MAINBOOK_ALLOWED_DIRS：允许本地读取和写入的文件夹，按平台 os.pathsep 分隔。MAINBOOK_MCP_TRANSPORT：stdio（默认）或 http。MAINBOOK_MCP_HOST：HTTP 绑定主机，默认 127.0.0.1。MAINBOOK_MCP_PORT：HTTP 绑定端口，默认 8000。MAINBOOK_MCP_OAUTH_ENABLED：托管 OAuth 验证器功能标志，默认 false。另有 OAuth 签发者、JWKS URL、资源、时钟偏差、最大令牌年龄、JWKS 缓存 TTL、未知 kid 刷新最小间隔等变量，以及 MCP_SERVICE_SIGNING_SECRETS（OAuth 启用时必需，切勿提交）。
【安装注意】 需要 Python 3.11 或更高版本，以及一个 MainBook 账户。应使用普通安装而非 pip install -e .，因为在该检出中可编辑安装写入的 .pth 文件不会被解释器拾取，导致 python -m mainbook_mcp 报 “No module named mainbook_mcp”，普通安装可完全绕过该问题。若希望优先使用操作系统钥匙串而非私有 JSON 回退，需在运行登录命令或本地服务器的每个环境中安装可选额外项。
