deposits

mcp-deposits

按客户分别持有的保证金和预付款，使用与发票相同的引擎。

保证金是存放在你账户上的客户资金。收到时必须记录，开具账单时抵扣发票，不需要时退还，并且在此期间随时都要能说明：你持有客户多少资金、使用什么币种、从何时开始持有。本服务通过 mcp-invoice 服务已有的发票和客户信息完成这四项操作。将保证金抵扣到发票时，付款会记录在该发票上，因此 invoice_list 和 overdue_report 不会再追讨你已经收到的款项。所有数据都保留在你的计算机上。

资金、币种和存储代码基于 @theluckystrike/mcp-invoice/lib 构建，A4 页面基于 @theluckystrike/mcp-billing-docs/lib 构建，因此保证金对账单的外观与旁边的贷项通知单和发票一致，金额精确到最小货币单位。

已加入 MCP 官方注册表（io.github.theluckystrike/deposits）。

@theluckystrike/mcp-deposits 的 npm 发布尚未完成，因此目前运行 npx -y @theluckystrike/mcp-deposits 会返回 404。在此之前，可使用 .mcpb 一键安装包，或克隆并构建。

安装

Claude Desktop（claude_desktop_config.json）：

{
  "mcpServers": {
    "deposits": {
      "command": "npx",
      "args": ["-y", "@theluckystrike/mcp-deposits"]
    }
  }
}

Claude Code：

claude mcp add deposits -- npx -y @theluckystrike/mcp-deposits

Cursor（.cursor/mcp.json）：

{
  "mcpServers": {
    "deposits": {
      "command": "npx",
      "args": ["-y", "@theluckystrike/mcp-deposits"]
    }
  }
}

同时运行 mcp-invoice：本服务会读取该服务中的发票和客户信息，将抵扣保证金产生的付款写入发票；两个服务也会从同一份企业资料中读取名称、地址、VAT id 和默认币种。

工具

工具	功能
deposit_record	记录收到的保证金或预付款：以最小货币单位计的金额、币种、日期和参考信息
deposit_list	列出所有保证金及其已收、已抵扣、已退款和持有金额。可按客户、状态、类型或日期筛选
deposit_apply	将部分或全部持有的保证金抵扣到发票上，作为该发票的一笔付款
deposit_refund	退还部分或全部持有的保证金，并记录日期和方式
deposit_delete	删除误录的保证金记录，但前提是从未抵扣或退款
deposit_balance	按客户和币种查看持有金额：已收、已抵扣、已退款和持有金额
deposit_statement_text	可粘贴到电子邮件中的纯文本对账单
deposit_statement_pdf	标题为 DEPOSIT STATEMENT（Pro）的 A4 PDF
deposits_report	按币种统计持有金额、持有时间最长的保证金，以及未抵扣达到 N 天的金额（Pro）
license_status、license_activate	查看免费版或 Pro 版状态，以及如何升级

一个资源 deposits://held，以及一个提示词 settle_deposits。

免费版与 Pro 版

	免费版	Pro 版
每个日历月记录的押金数	5	不限
用于发票、退款、余额、列表	是，不限	是
对从未发生资金流动的押金使用 deposit_delete	是，不限	是
deposit_statement_text	是，不限	是
deposit_statement_pdf	否	是，另含您的徽标且不带页脚署名
deposits_report	否	是

免费版的上限只针对新记录的押金。已持有的资金在任何套餐中都可以随时用于支付、退款和入账：如果限制导致客户的押金无法使用，受限的就是客户的钱，而不是您的钱。

上限按当月收到日期的押金记录数计算，因此 deposit_delete 会立即返还名额：重复录入或金额有误的押金，除了占用 ID 外不花费任何成本。deposit_record 也会拒绝与已有记录在客户、金额、币种、类型、收到日期和参考信息上都相符的押金，并返回该记录的 ID，且不会存储任何内容，因此同一笔资金绝不会被重复持有，重试也不会占用免费名额。

获取 Pro 版：https://mcp.zovo.one/buy/deposits（此服务一次性收费 $19，套装收费 $39）。

一个实测案例

**发票服务自身的收款工具会将已付金额设为指定数值，因此通过它处理押金会抹掉之前的付款。**根据 servers/invoice/dist/index.js 的实测，在一张金额为 EUR 1,000.00 的发票上，先使用 invoice_mark_paid {amount: 200} 记录银行转账，再使用 invoice_mark_paid {amount: 300} 记录押金，结果 paid_minor 变成 30000，回复显示“应付余额 EUR 700.00”。实际到账的 EUR 200.00 从记录中消失了，客户也会因此被催款。

deposit_apply 会在同一条记录上写入相同的三个字段：paid_minor、paid_date、status，但它会累加：相同的两笔付款会使 paid_minor 达到 50000，应付余额为 EUR 500.00。此行为已在 test/unit.test.mjs 中通过断言验证：“第二次应用会累加到 paid_minor，而不是替换它”。

一般而言：两个服务共享的存储，只有在你了解负责该存储的服务如何写入数据时，才可以安全写入。字段名称一致并不代表遵循了约定；对这些字段的运算方式才是关键。

隐私

所有数据都保留在本地：${XDG_DATA_HOME:-~/.local/share}/mcp-servers/deposits/。无需账户、API 密钥，也不会进行网络调用。许可证密钥会离线验证。

由 theluckystrike 构建。支持邮箱：[email protected]

将这些文档用作 MCP 服务

任何 MCP 客户端（Claude、Cursor、Windsurf、VS Code）都可以通过 GitMCP 直接读取此仓库的文档，无需安装：

• 文档 MCP URL：https://gitmcp.io/theluckystrike/mcp-deposits