Skip to main content
Glama
Sign In
yimu-mcp

yimu-mcp

by powercess
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

yimu-mcp

一木记账（yimubill.com）的 MCP 服务：把一木记账网页版的能力封装成 AI 可调用的工具， 在支持 MCP 的客户端里就能直接读写你的账本。

能做什么

  • 三种登录方式：扫码登录（推荐，手机一扫即可）、邮箱密码登录、直接配置登录令牌

  • 看账：全量/增量同步账单、按账本分页查询、账单总数、删除记录

  • 管账：新增、更新、删除账单、资产、账本、标签、转账、借贷、分类、报销、退款、附件

  • 辅助能力：一句话记账解析（「午饭 35」自动识别金额和分类）、可显式启用的通用接口请求

  • 扫码方便：二维码直接显示在对话或终端里，不用打开图片文件

Related MCP server: manager-mcp

快速开始

需要 Node ≥ 23.4 或 Bun ≥ 1.x。

安装：

npm install -g @powercess/yimu-mcp
yimu-mcp        # 启动 MCP 服务

本地开发：

npm install && npm run build   # Node
# 或
bun install && bun run dev      # Bun，直接运行，无需构建

配置

建议通过环境变量提供配置，账号信息不进仓库：

环境变量

说明

YIMU_TOKEN

登录令牌 JWT（登录后获得，优先级最高）

YIMU_EMAIL / YIMU_PASSWORD

账号邮箱/密码（可选：未配 TOKEN 时启动自动登录；login_email 不传参时用这对凭据）

YIMU_USER_ID

用户 ID（部分接口需要，登录后自动获取）

YIMU_BASE_URL

兼容配置项，仅接受官方 https://yimubill.com/api（可带结尾 /）

YIMU_QR_DIR

二维码保存目录，默认系统临时目录

YIMU_CONFIG

可选，显式指定可信 JSON 配置文件的绝对路径；也可使用 --config

YIMU_ENABLE_API_REQUEST

仅设为 1 时启用通用接口工具；也可使用 --enable-api-request

不再自动读取启动目录中的 yimu.config.json。需要文件配置时，请使用 --config /绝对路径/yimu.config.json 或 YIMU_CONFIG 指向由你管理的可信文件。优先级为命令行参数 > 环境变量 > 显式文件 > 默认值； 显式文件不存在、不是有效 JSON 对象或使用相对路径时，启动会失败。API 地址始终受官方域名限制。

令牌可从一木记账网页版浏览器开发者工具里复制请求头 token 的值。

接入 MCP 客户端

全局安装后：

{
  "mcpServers": {
    "yimu": {
      "command": "yimu-mcp",
      "env": { "YIMU_TOKEN": "你的JWT" }
    }
  }
}

仓库本地方式（command 指向可执行文件）：node + dist/index.js，或 bun + src/index.ts（无需构建）。

登录

  1. 扫码登录（推荐）：调用 login_qr_start，二维码直接显示在对话或终端里； 手机打开一木记账 App，首页 → 更多 → 扫一扫，扫完调用 login_qr_poll 等待登录结果。

  2. 邮箱密码登录：调用 login_email，填邮箱和密码即可，密码加密传输； 不传参数时自动使用环境变量 YIMU_EMAIL / YIMU_PASSWORD。

  3. JWT 直配：在环境变量里配好 YIMU_TOKEN，启动即已登录。

配了 YIMU_EMAIL / YIMU_PASSWORD 而未配 TOKEN 时，服务启动会自动登录获取 JWT， AI 即可直接读写账本；令牌过期后随时调 login_email（无参）重新登录。 扫码/邮箱登录只返回登录状态和脱敏用户信息，JWT 留在当前工具进程内部供后续请求使用。 新 JWT 只更新内存，不写回环境变量或配置文件；重启后仍需原有有效配置或重新登录。

安全说明

  • 密码提交时按官方协议使用 AES-128-ECB 加密；传输保密依赖 HTTPS。工具不自动保存登录凭据， --print-config 对令牌和密码掩码；使用文件配置时，文件权限和保存方式由你管理。

  • 请求仅发送至 https://yimubill.com，并拒绝自动重定向；不能通过配置改为代理、HTTP 或其他域名。

  • MCP 输出统一移除凭据字段和已知秘密的回显；错误结果仅保留安全的状态或错误码，不透传服务器原文。

  • 扫码二维码和会话 ID 仍通过 MCP 交互展示，用于完成登录；这些是短期登录授权信息，仅应交给可信客户端。

  • api_request 默认不注册，显式启用后其 raw 模式仍会脱敏。get_sts / get_sts_no_verify 不再作为 MCP 工具公开，避免把对象存储临时凭据交给模型；内部 API 方法保留。

  • 在 hub 等平台配置 YIMU_PASSWORD 前，请确认其环境变量存储方式；优先用 YIMU_TOKEN 或扫码登录。

工具一览

  • 登录与账号：login_qr_start login_qr_poll login_email get_me auth_status

  • 查询：sync_pull（增量同步，默认返回摘要：计数/收支合计/最近明细/分类Top）、get_bill_count（账单总数）、 get_book_bills（账本账单分页，精简账单+收支小计）、 get_assets（资产，仅业务字段）、get_currency（币种）、get_category_info（分类）、 get_share_accounts（共享账本）、get_account_members（账本成员）、get_delete_history（删除记录）

  • 记账：save_bill / save_bills（单条/批量新增或更新）、delete_bill（删除）

  • 其他实体：save_asset save_account_book save_tag save_transfer save_lend save_parent_category save_child_category save_reimbursement save_refund save_bill_file save_bill_import save_asset_history（对应删除用 delete_*）

  • 辅助：parse_bill_text（一句话记账解析）、api_request（仅显式启用时，通用请求仍可读写接口）

测试

运行 npm ci --ignore-scripts 和 npm test，会先编译再执行 Node 测试。 回归测试使用模拟 API 响应、真实 MCP 内存传输和临时配置文件，不连接一木服务、不需要真实账号。 覆盖登录后继续认证、凭据输出、错误信息、恶意配置、地址校验和重定向策略。

License

MIT

Available Tools

45 tools
auth_statusauth_statusA

查看登录状态（本地配置，不发请求）：是否持有 JWT、用户 ID、API 基址。

Inputs: no named parameters.

delete_account_bookdelete_account_bookA

删除账本（POST /accountBook/deleteAccountBook）。entity 需携带主键字段（accountBookId）与 userId。

Inputs: entity (required).

delete_assetdelete_assetA

删除资产（POST /asset/deleteAsset）。entity 需携带主键字段（assetId）与 userId。

Inputs: entity (required).

delete_asset_historydelete_asset_historyA

删除资产变动记录（POST /assetHistory/deleteAssetHistory）。entity 需携带主键字段（assetHistoryId）与 userId。

Inputs: entity (required).

delete_billdelete_billC

删除账单（POST /bill/deleteBill，按 billId 删除）。

Inputs: bill_id (required), user_id.

delete_bill_filedelete_bill_fileA

删除账单附件（POST /billFile/deleteBillFile）。entity 需携带主键字段（fileId）与 userId。

Inputs: entity (required).

delete_child_categorydelete_child_categoryA

删除二级分类（POST /childCategory/deleteChildCategory）。entity 需携带主键字段（categoryId）与 userId。

Inputs: entity (required).

delete_lenddelete_lendA

删除借贷（POST /lend/deleteLend）。entity 需携带主键字段（lendId）与 userId。

Inputs: entity (required).

delete_parent_categorydelete_parent_categoryA

删除一级分类（POST /parentCategory/deleteParentCategory）。entity 需携带主键字段（categoryId）与 userId。

Inputs: entity (required).

delete_refunddelete_refundB

删除退款（POST /refund/deleteRefund）。entity 需携带主键字段（refundId）与 userId。

Inputs: entity (required).

delete_reimbursementdelete_reimbursementA

删除报销（POST /reimbursement/deleteReimbursement）。entity 需携带主键字段（reimbursementId）与 userId。

Inputs: entity (required).

delete_tagdelete_tagB

删除标签（POST /tag/deleteTag）。entity 需携带主键字段（tagId）与 userId。

Inputs: entity (required).

delete_transferdelete_transferB

删除转账（POST /transfer/deleteTransfer）。entity 需携带主键字段（transferId）与 userId。

Inputs: entity (required).

get_account_delete_historyget_account_delete_historyC

查询账本删除历史（GET /accountBook/getAccountDeleteHistory/{userId}/{ownerId}/{bookId}/{lastSyncTime}）。

Inputs: book_id (required), user_id, owner_id, last_sync_time.

get_account_membersget_account_membersC

查询账本成员（GET /accountBook/getAccountMember/{userId}/{bookId}）。

Inputs: book_id (required), user_id.

get_assetsget_assetsA

查询资产列表（GET /asset/getAsset/{userId}/{time}），time 为起始时间戳(ms)，缺省 0 全量；每个资产只保留业务字段（名称/余额/类型/分组）。

Inputs: time, user_id.

get_bill_countget_bill_countC

查询账单总数（GET /bill/getBillCount/{userId}）。

Inputs: user_id.

get_book_billsget_book_billsA

分页查询账本账单（GET /bill/getAccountBillPage/{userId}/{bookId}/{page}）。返回 {syncTime, hasMoreData, billCount, totals:{income,expense}, bills:[精简账单]}；账单只含 billId/cost/日期/分类/备注/账户等业务字段。page 从 0 起，按 hasMoreData 翻页。

Inputs: book_id (required), page, user_id.

get_book_last_timeget_book_last_timeA

查询账本最后同步时间戳(ms)（GET /bill/getAccountLastTime/{userId}/{bookId}），可作增量同步游标。

Inputs: book_id (required), user_id.

get_category_infoget_category_infoC

查询分类信息（图标/预设分类，GET /icon/getCategoryInfo/{userId}）。

Inputs: user_id.

get_currencyget_currencyB

查询币种数据（GET /currency/getCurrencyData/{userId}）。

Inputs: user_id.

get_delete_historyget_delete_historyB

查询删除记录（GET /deleteHistory/getDeleteHistory/{userId}/{time}），time 缺省 0 全量。

Inputs: time, user_id.

get_meget_meA

查询当前用户信息（POST /user/getUserInfoById）；响应顶层 token 会自动刷新 JWT。

Inputs: user_id.

get_share_accountsget_share_accountsB

查询共享账本列表（GET /accountBook/getShareAccount/{userId}）。

Inputs: user_id.

login_emaillogin_emailA

邮箱密码登录（免鉴权）。密码按网页端加密方案（AES-128-ECB）加密后提交；仅返回登录状态与用户对象。不传 email/password 时使用环境变量 YIMU_EMAIL/YIMU_PASSWORD（未配置则报错）。请优先使用扫码登录（更安全）。

Inputs: email, password.

login_qr_polllogin_qr_pollA

等待/轮询扫码登录结果（免鉴权）。timeout 秒内每 3 秒查询一次，用户扫码后返回 status=success 与用户对象（JWT 仅保留在当前进程内部）；timeout=0 只查一次。默认 120 秒。

Inputs: session_id (required), timeout.

login_qr_startlogin_qr_startA

创建扫码登录会话（免鉴权）。返回 session_id、qr_payload（login:<session_id>）与二维码图片：

  1. 结果附带的 image 内容块可直接在支持图片的 harness 界面展示；

  2. text 中内嵌 UTF-8 终端二维码（等宽字体直显，无需打开图片）；

  3. 图片同时保存到二维码目录（--qr-dir / YIMU_QR_DIR，默认系统临时目录 yimu-mcp/），text 中给出完整路径；

  4. 服务端同时把 ANSI 彩色二维码打印到 stderr（服务运行在终端里时控制台直接可见）。 二维码 2 分钟有效，用一木记账 App【首页】-【更多】-【扫一扫】扫描后调用 login_qr_poll 等待登录结果。

Inputs: no named parameters.

parse_bill_textparse_bill_textA

解析记账原始文本（GET /bill/analysisBillInfoT/{userId}/{text}），返回结构化账单信息。

Inputs: text (required), user_id.

save_account_booksave_account_bookB

新增或更新账本（POST /accountBook/addOrUpdateAccountBook，upsert：带主键为更新）。entity 字段：accountBookId 主键；bookName 账本名；bookType 账本类型；shareUsers 共享用户；字段按服务端契约传递

Inputs: entity (required).

save_assetsave_assetA

新增或更新资产（POST /asset/addOrUpdateAsset，upsert：带主键为更新）。entity 字段：assetId 主键；assetName 名称；assetType 类型；assetNumber 余额；totalQuota 总额度；intoTotalAsset 计入总资产；hide 隐藏；bookId 账本；currency 币种；remark/simpleName/cardCode/positionWeight 可选；userId/updateTime 自动填充

Inputs: entity (required).

save_asset_historysave_asset_historyA

新增或更新资产变动记录（POST /assetHistory/addOrUpdateAssetHistory，upsert：带主键为更新）。entity 字段：assetHistoryId 主键；assetId 账户；time 时间；currentNum 变动后余额；changeNum 变动额；changeContent 变动说明

Inputs: entity (required).

save_billsave_billA

新增或更新账单（POST /bill/addOrUpdateBill，upsert：带 billId 为更新，缺省为新增）。自动归一化：tags 数组→JSON 字符串、recordTime 缺省取 updateTime/当前时间、billId 超 int32 自动重生成。bill 字段： billId 主键；cost 金额（元）；time 记账时间(ms)；billType 记录方式（1快捷/2手动/3导入/4周期/5自动/6模板）；parentCategoryId/childCategoryId 分类（收支由分类决定）；remark 备注；assetId 账户；bookId 账本；tags 标签（数组或 JSON 字符串均可）；recordTime 记录时间；reimbursement/reimbursementEnd 报销；notIntoTotal/notIntoBudget 不计收支/预算；currencyInfo 币种；userId/updateTime 自动填充

Inputs: bill (required).

save_bill_filesave_bill_fileA

新增或更新账单附件（POST /billFile/addOrUpdateBillFile，upsert：带主键为更新）。entity 字段：fileId 主键；billId 关联账单；remotePath 远程路径；fileName 文件名；fileSize 大小；transferId/lendId 可选

Inputs: entity (required).

save_bill_importsave_bill_importB

新增或更新账单导入记录（POST /billImport/addOrUpdateBillImport，upsert：带主键为更新）。entity 字段：billImport 导入记录；无快照数据，按服务端契约传递

Inputs: entity (required).

save_billssave_billsA

批量新增/更新账单（POST /bill/addOrUpdateBillList）。自动按 100 条分批、每批 updateTime 递增（与网页端一致）。bill 字段同 save_bill。

Inputs: bills (required).

save_child_categorysave_child_categoryA

新增或更新二级分类（POST /childCategory/addOrUpdateChildCategory，upsert：带主键为更新）。entity 字段：categoryId 主键；categoryName 名称；iconUrl 图标；parentCategoryId 所属一级分类；positionWeight 排序；hide 隐藏；categoryType 类型

Inputs: entity (required).

save_lendsave_lendA

新增或更新借贷（POST /lend/addOrUpdateLend，upsert：带主键为更新）。entity 字段：lendId 主键；type 类型（借出/借入）；number 金额；interest 利息；outTime/inTime 借出/归还时间；assetId 关联账户；repaymentAssetId 还款账户；remark 备注

Inputs: entity (required).

save_parent_categorysave_parent_categoryB

新增或更新一级分类（POST /parentCategory/addOrUpdateParentCategory，upsert：带主键为更新）。entity 字段：categoryId 主键；categoryName 名称；iconUrl 图标；positionWeight 排序；hide 隐藏；categoryType 类型

Inputs: entity (required).

save_refundsave_refundA

新增或更新退款（POST /refund/addOrUpdateRefund，upsert：带主键为更新）。entity 字段：refundId 主键；billId 关联账单；refundNum 退款金额；refundInfos 退款明细（JSON）

Inputs: entity (required).

save_reimbursementsave_reimbursementA

新增或更新报销（POST /reimbursement/addOrUpdateReimbursement，upsert：带主键为更新）。entity 字段：reimbursement 无快照数据；携带 billId/remark/金额字段与 userId，按服务端契约传递

Inputs: entity (required).

save_tagsave_tagA

新增或更新标签（POST /tag/addOrUpdateTag，upsert：带主键为更新）。entity 字段：tag 字段无快照数据；至少携带 tagId/tagName 与 userId，其余按服务端契约传递

Inputs: entity (required).

save_transfersave_transferA

新增或更新转账（POST /transfer/addOrUpdateTransfer，upsert：带主键为更新）。entity 字段：transferId 主键；cost 金额；serviceCharge 手续费；time 时间；fromAssetId/toAssetId 转出/转入账户；toCost 到账金额；billId 关联账单；remark 备注

Inputs: entity (required).

sync_endsync_endA

结束同步限流会话（免鉴权，POST /bookkeeping/rateLimit/sync/end?sessionId=）。

Inputs: session_id.

sync_pullsync_pullA

增量拉取业务数据（GET /updateTime/getUpdateDataPage/{userId}/{time}）。默认返回摘要：syncTime、各实体计数、收支合计、最近10笔、分类Top10、资产列表——适合 AI 快速分析账目；需要完整明细时传 summary=false，各实体按业务字段精简返回（Bill 只含 billId/cost/日期/分类/备注等）。time 为上次同步时间戳(ms)，缺省 0 表示全量。

Inputs: time, summary, user_id.

sync_startsync_startA

开始同步限流会话（免鉴权，POST /bookkeeping/rateLimit/sync/start）。批量写操作前先 start，全部完成后务必 sync_end 归还会话，避免触发限流。返回 {syncCount, sessionId}。

Inputs: no named parameters.

Tool Schema Changelog

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

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    B3.4/5.0

    Scored across 45 tools

    Disambiguation4/5

    Most tools are clearly separated by entity-specific CRUD verbs (save_bill, delete_asset, save_transfer, etc.), so an agent can usually pick the right one. Some overlap remains around data retrieval and sync concepts (sync_pull vs get_book_bills vs sync_start/sync_end) and between general delete history and account-book delete history.

    Naming Consistency5/5

    Tool names consistently use snake_case with a predictable verb_noun pattern: get_*, save_*, delete_*, login_*, sync_*, and a few auth/parse helpers. The convention is stable across all 45 tools with no style mixing.

    Tool Count2/5

    45 tools is far above the typical well-scoped range and creates a large surface for an agent to navigate. The domain is broad, but the sheer number of entity-specific save/delete pairs makes the set heavy and easy to misuse.

    Completeness4/5

    Core bookkeeping lifecycles are covered through save/delete tools plus sync_pull and paginated bill queries, which can retrieve broader entity data. Dedicated read/list tools are missing for several entities (tags, transfers, lends, reimbursements, refunds, bill files), and delete coverage is not perfectly uniform, but these are workable gaps.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • EzBookkeeping MCP Server

      theanirudhvyas
      A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to interact with EzBookkeeping for personal finance management through natural language, including adding transactions, checking balances, and generating reports.
      MIT

    • manager-mcp

      onexurOSS
      A
      license
      B
      quality
      B
      maintenance
      Enables AI assistants to query and manage self-hosted accounting data—invoices, balances, and books—through natural language, with read-only tools by default and optional scoped write operations.
      30
      25 PyPI
      1
      AGPL 3.0

    • Smart Money MCP

      ultraza4
      A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to manage personal finances through plain-language commands, including expense logging, account and deposit tracking, budget monitoring, and spending reports, with OAuth-secured access to a shared ledger.
      MIT

    • CatWallet MCP Server

      yueyue95
      A
      license
      Not graded
      quality
      B
      maintenance
      Enables compatible AI clients to read stored personal-finance data and, with explicit user authorization, perform supported mutations under the same ownership checks as the web app.
      MIT