Skip to main content
Glama
鲨鱼记账 MCP

鲨鱼记账 MCP

by varmeto

鲨鱼记账 MCP

一个给 AI agent 使用的本地账目采集工具。它通过 Android 调试接口读取鲨鱼记账应用中可见的账目详情,按月核对收入和支出,再导出 CSV,方便用 Excel、WPS 或其他工具查看。

如果你的账目留在鲨鱼记账里,希望让支持 MCP 的 agent 协助备份,这个项目提供了一条不用 VIP 导出功能、不需要 root 的方式。它操作手机上已经登录的应用界面;本工具不调用鲨鱼记账的服务端接口。

目前是实验版,不是通用的一键迁移工具。 已实机验证的环境只有:Android 版鲨鱼记账 5.86.1、vivo V2229A、1916 × 2160 屏幕。工具会拒绝其他应用版本或屏幕尺寸;即使尺寸相同,其他设备的界面布局也可能不同,使用前应先用少量数据验证。

能做什么

  • 让 agent 检查手机连接、应用版本和屏幕尺寸。

  • 读取当前选中月份的可见账目,包括日期、收支类型、分类、金额以及详情页显示的备注。

  • 每读取一笔就保存原始界面数据,并将当月采集金额与应用显示的月度收入、支出核对。

  • 将通过检查的月份导出为 CSV;中断或失败时保留已采集内容供排查。

每次只处理当前选择的一个月。你需要手动切换月份和账本、确认列表处于顶部,并在采集前关闭应用里的“快捷编辑”。工具不会自动覆盖已有导出文件。

月度金额相同并不能单独证明所有记录都采全:遗漏与重复可能抵消,同金额记录也可能混淆。请另外核对日期范围、应用总笔数和各账本。详情页没显示的账户、标签、图片等内容,以及其他账号或未同步的数据,不能保证包含在结果中。

Related MCP server: MCP Agent - AI Expense Tracker

准备

  1. 在电脑上安装 Python 3.11 或更新版本、uv 和 Android platform-tools(adb)。

  2. 克隆仓库,记下本地目录的绝对路径:

    git clone https://github.com/varmeto/shark-ledger-mcp.git
  3. 在 Android 手机上开启开发者选项和 USB 调试,连接电脑并在手机上批准调试授权。也可以使用已配对的无线调试。

  4. 在电脑运行 adb devices -l,确认目标设备状态为 device。解锁手机并打开鲨鱼记账。

连接你的 AI agent

将以下示例加入支持 stdio MCP 的客户端配置。把两个路径改成你电脑上实际存在的位置;配置文件的位置和格式请以所用客户端的文档为准。

{
  "mcpServers": {
    "shark-ledger": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/shark-ledger-mcp", "python", "server.py"],
      "env": {"SHARK_DATA_DIR": "/absolute/path/to/private-data"}
    }
  }
}

Windows 用户应将示例路径改为本机的绝对路径,并按 JSON 规则转义反斜杠;目前 Windows 尚未实机验证。如果客户端找不到 uv,可在 command 中填写 uv 可执行文件的绝对路径。首次运行可能需要下载 Python 依赖。

SHARK_DATA_DIR 是保存私人数据的目录;省略时默认为 ~/.local/share/shark-ledger-mcp。请把它放在仓库之外。服务使用本地 stdio,不会自己打开网络端口。

采集一份账单

  1. 在鲨鱼记账设置中关闭“快捷编辑”。此功能开启时,点击列表可能进入编辑界面。

  2. 打开你要采集的主账本和月份,手动把账目列表滚到该月最上方。

  3. 告诉 agent,例如:“请用鲨鱼记账 MCP 检查手机连接,采集当前月份并导出 CSV。快捷编辑已关闭,列表已在顶部。” agent 会使用 diagnose 和 start_month_capture。

  4. 采集时不要操作手机。agent 可以通过 capture_status 查看进度;需要停止时可调用 cancel_capture。每笔详情的原始 XML 和 JSON 保存在私人数据目录中。

  5. 检查采集状态和 records.json;对下一个月重复上述步骤。完成后恢复“快捷编辑”原来的设置。

  6. 使用 export_csv 导出已通过核对的月份,并对照应用检查总笔数和范围。导出的 CSV 可用 Excel 或 WPS 打开。

采集器会模拟点击账目、返回和滚动;如果详情与列表不匹配、月份发生变化或金额核对失败,应停止并检查。请勿让 agent 自动点击应用里的编辑、删除或分享。

MCP 工具

工具

用途

diagnose(serial)

检查 ADB、应用版本、前台状态和屏幕尺寸,不读取账目。

start_month_capture(serial, output_name, quick_edit_disabled, at_month_top)

开始采集当前月;两个布尔值只能在手机上确认后设为 true。output_name 必须是尚不存在的简单目录名。

capture_status()

查看进度和相对于数据目录的批次路径;私有 capture.log 可用于排错。

cancel_capture()

停止采集,保留已保存的部分结果。

export_csv(capture_paths, output_name)

将通过核对的 records.json 导出为新 CSV;所有路径相对于 SHARK_DATA_DIR。

中断后不会自动从断点续跑。同一个月多次采集时,需要人工核对重叠;导出器会拒绝同月多批、未完成、有警告或金额不匹配的批次。

隐私与排错

账目、原始 XML、日志和 CSV 都可能包含敏感信息。工具本身只将数据写入本地,但所用 agent 或 MCP 客户端的日志、对话上下文和备份策略不由本项目控制。不要把真实数据、设备序列号、令牌或截图提交到公开仓库。

连接失败时先运行 adb devices -l 检查授权和连接,再调用 diagnose。检查应用版本、屏幕尺寸、前台页面、列表位置和“快捷编辑”状态。采集日志位于对应批次目录下的 capture.log;分享日志前请自行检查并删除个人信息。

开发者可运行:

uv sync
uv run python -m unittest -v

本项目是独立工具,与鲨鱼记账官方无关联。开源许可证见 LICENSE。

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables personal financial management through AI assistants by providing tools to add transactions, check balances, list transaction history, and generate monthly summaries. Supports natural language interaction for tracking income and expenses with categorization.
      1
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables personal expense management through CSV storage, allowing AI agents to add, query, and analyze expenses with automatic categorization and payment method validation.
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      A personal financial management tool that enables AI assistants to record transactions, check balances, and provide monthly financial summaries via the Model Context Protocol. It allows users to manage their expenses and income through natural language interactions using standardized MCP tools and resources.
      -