recurring-invoice-scheduler-subscription-billing-due-reminders

mcp-recurring

只需说一次“每月 1 日以 90 EUR 的单价向 Acme 开具 12 小时的账单”，之后就不用再记着这件事了。此 MCP 服务会存储定期发票计划、客户、明细项、周期以及开始和结束日期；然后在你提出请求时，将实际到期的发票作为真实记录写入 invoice server，使用其中的编号序列、客户资料和 A4 PDF。生成操作具有幂等性：每个计划在每个周期最多生成一张发票，并以发生日期作为键，因此同一天运行两次账单处理，第二次不会创建任何内容。它还能回答“未来 30 天有哪些款项到期”和“未来一年每个月我会开具多少发票”等问题。所有内容都以纯 JSON 文件的形式存储在你自己的设备上，不会上传到任何地方。

已收录于 官方 MCP Registry（io.github.theluckystrike/recurring-invoice-scheduler-subscription-billing-due-reminders）。

只需定义一次重复发票，即可通过聊天生成到期的 PDF，无需账单 SaaS。

60 秒安装

@theluckystrike/mcp-recurring 的 npm 发布尚待完成。在此之前，可使用 .mcpb 一键安装包，或克隆后构建； 以下两种方式均已验证。

一键安装（.mcpb）：从最新版本下载 recurring.mcpb，然后在 Claude Desktop 中双击： https://github.com/theluckystrike/mcp-servers/releases/latest

（claude_desktop_config.json）：

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

Claude Code：

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

（.cursor/mcp.json）：

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

上面的 npx 方式将在软件包发布后立即可用。在此之前，请使用上面的 .mcpb 安装包，或通过以下三条命令从源代码构建：

git clone https://github.com/theluckystrike/mcp-servers.git && cd mcp-servers
npm install
npm run build -w packages/mcp-license -w servers/invoice -w servers/recurring

然后将客户端的 command 指向 node，并提供一个参数：servers/recurring/dist/index.js 的绝对路径。

若要在 Pro 模式下运行，请在同一配置块中设置 MCP_LICENSE_KEY，或使用你的密钥调用一次 license_activate。

搭配使用

• mcp-invoice，实际使用时必需，但代码层面并非必需。此服务会将数据写入发票服务的数据目录，并共用其编号计数器、客户列表和企业资料，因此每张生成的发票都会显示在 invoice_list 中、计入 overdue_report，并可使用 invoice_pdf 重新渲染。请在那里使用 business_set 设置一次开票方信息；此服务特意不提供自己的 business_set，确保只需维护一份资料。
• mcp-time-tracker，用于处理不属于固定服务费的工时。跟踪工时，按需开具发票，并将每月固定部分交由此处的计划处理。
• mcp-expense-tracker，每月变动的可转收费成本应放在按需发票中；计划适用于金额固定不变的部分。

工具

工具	功能
schedule_create	定义重复账单：客户、项目、频率、开始日期、可选结束日期、付款期限、备注
schedule_list	列出所有计划及其频率、每期金额、下次到期日和状态
schedule_get	查看单个计划的完整记录，以及已生成的账单数量
schedule_update	更改客户、项目、货币、频率、日期、付款期限或备注。已开具账单的周期不会重新开票
schedule_pause	停止生成账单，但不删除计划；保留历史记录
schedule_resume	重新启用计划。暂停期间已到期的周期仍然需要开票
schedule_delete	删除计划。该计划生成的账单仍保留在账单服务中，并保留历史记录作为审计追踪。重新创建的计划会获得新 ID，因此当 invoice_generate_due 再次覆盖旧计划已开票的周期时，会发出警告
schedule_skip	永久跳过某一次周期，不暂停计划——适用于“10 月不要向这位客户开票”。设置 undo: true 可恢复该周期
schedule_upcoming	查看未来 N 天内到期的项目、金额和各货币合计，以及已经到期但尚未开票的周期。免费版覆盖 30 天
invoice_generate_due	按指定日期生成到期账单并渲染 PDF。以周期为键，具备幂等性；会报告已创建和已跳过的账单。每次调用最多生成 60 张账单，按周期从早到晚处理，并告知仍有多少张待处理。dry_run 可预览运行结果。免费且不限量
schedule_history	Pro：查看单个计划的审计日志——每个周期、账单编号、日期、金额、付款状态和 PDF 路径
forecast	按日历月和货币预测收入，并单独列出暂停的计划，而非将其排除。免费版覆盖 3 个月
license_status	显示免费版或 Pro 模式
license_activate	激活 Pro 密钥（离线验证）

资源：recurring://upcoming 以 JSON 格式返回未来 30 天内的周期。 提示词：monthly_billing_run，先试运行，再生成账单、列出即将到期的项目，然后报告哪些客户需要付款提醒。

你可以这样说

你说	工具
“每月 1 日起，每小时 90 EUR，向 Acme 开 12 小时的账单。”	schedule_create
“我有哪些重复账单？”	schedule_list
“未来 30 天内有哪些账单到期？”	schedule_upcoming
“处理本月账单。”	monthly_billing_run / invoice_generate_due
“创建之前，先给我看看将会生成哪些账单。”	invoice_generate_due {dry_run: true}
“暂停 Beta Corp 的长期服务合同，他们暂时搁置了。”	schedule_pause
“10 月不要向 Acme 开账单。”	schedule_skip
“从现在起，将 Acme 的长期服务合同费率提高到每小时 100 EUR。”	schedule_update
“明年我每月会开出多少账单？”	forecast
“列出这份长期服务合同生成的所有账单。”	schedule_history

示例

You: Bill Acme 12 hours at 90 EUR a month, starting 1 June, 14 day terms.

  schedule_create {
    client: "Acme Retainer", currency: "EUR", every: "monthly",
    start_date: "2026-06-01", due_days: 14,
    items: [{ description: "Retainer hours", quantity: 12, unit_price: 90 }]
  }
  -> schedule 9f2c1a04, next dates 2026-06-01, 2026-07-01, 2026-08-01, 2026-09-01

You (on 3 September): Run the billing.

  invoice_generate_due {}
  -> as_of 2026-09-03: created 4 invoices, skipped 0 already invoiced.
     INV-2026-0001  Acme Retainer  period 2026-06-01  EUR 1080.00  due 2026-06-15  .../pdf/INV-2026-0001.pdf
     INV-2026-0002  Acme Retainer  period 2026-07-01  EUR 1080.00  due 2026-07-15  .../pdf/INV-2026-0002.pdf
     INV-2026-0003  Acme Retainer  period 2026-08-01  EUR 1080.00  due 2026-08-15  .../pdf/INV-2026-0003.pdf
     INV-2026-0004  Acme Retainer  period 2026-09-01  EUR 1080.00  due 2026-09-15  .../pdf/INV-2026-0004.pdf
     Total: EUR 4320.00

You (five minutes later, having forgotten): Run the billing.

  invoice_generate_due {}
  -> as_of 2026-09-03: created 0 invoices, skipped 4 already invoiced.

第二次运行最能说明问题：关键在于周期，而不是日历日期，因此重复运行账单流程不会产生任何操作，也不会在客户收件箱中造成重复账单。

免费版与 Pro

	免费版	Pro
活跃计划	3	不限量
invoice_generate_due	是，不限量	是，不限量
schedule_upcoming 时间范围	30 天	最长 10 年
forecast	3 个月	最长 120 个月
schedule_history 审计日志	否	是
月末和锚定日规则（anchor_day、end_of_month）	否，按开始日期的日号开票	是
暂停、恢复、更新、删除、试运行、多币种	是	是

Pro 一次性付费 $19；支付 $39 可用于合集中的每个服务，终身有效。

日期：月末会发生什么

每个日期都是本地 ISO 日历日期，格式为 YYYY-MM-DD。一次发生是从 start_date 开始的第 k 步，发生次数 0 就是 start_date 本身，因此，从今天开始的计划今天就到期。

• weekly = 每步 +7 天。{days: n} = 每步 +n 天。
• monthly = +1 个月，quarterly = +3 个月，yearly = +12 个月。
• 月末。 月份步进会保留 start_date 的月中日期，并将其限制在目标月份的天数范围内；这个限制不会延续到后续月份。从 2026-01-31 开始的序列依次为 01-31、02-28、03-31、04-30、05-31；二月不会悄悄把月末周期付款变成每月 28 日付款。
• 2 月 29 日。 同一规则意味着，以 2028-02-29 开始的年度计划在平年会落在 02-28，并在下一个闰年回到 02-29。
• anchor_day / end_of_month（Pro）。 anchor_day 会在限制日期前替换月中日期，因此 anchor_day: 31 表示每月最后一天；end_of_month: true 也会明确执行相同操作。对于 weekly 和 {days: n}，由于没有可供锚定的月份，两者均会被忽略。如果锚定后的首次发生日期早于 start_date，则会舍弃该次发生，绝不会提前扣款。
• end_date 包含在内。 恰好落在 end_date 的发生会生成；下一次则不会。
• 长期计划。 查询到期项目时，不会从 start_date 重新回放整个计划：系统会跳转到接近所查询日期的估算位置，再从那里向前扫描。因此，2010 年创建的每日计划在 2026 年仍能报告到期项目，而不会逐日遍历到该日期，耗尽每次运行的发生次数上限。

金额

发票引擎会以整数最小货币单位保存金额，使用相同的 ISO 4217 表，并遵循相同的“逐行舍入后再求和”约定，因此，计划金额与其生成的发票绝不会不一致。每一行的总额会先行舍入，税额按行计算并舍入，再按税率合并为一行；总计则是这些已舍入数值的整数之和。计划使用自身的 currency，如果未设置，则使用你的企业默认货币；此处不会进行货币兑换。

数据存储方式

计划和生成日志保存在 ${XDG_DATA_HOME:-~/.local/share}/mcp-servers/recurring/ 中，文件名为 schedules.json 和 history.json。它们 保存在发票服务的目录 ${XDG_DATA_HOME:-~/.local/share}/mcp-servers/invoice/ 中， PDF 文件则放在其 pdf/ 子目录下；invoice_list、overdue_report 和 invoice_pdf 会读取这些相同的文件。

每次修改都会在咨询锁文件保护下执行。任何会写入发票的操作都会获取两个锁，且始终按相同顺序获取：先获取 recurring/.lock，再获取 invoice/.lock，这样，两次账单生成操作（或一次账单生成操作与另一个服务中的手动发票操作）就不会交错执行、分配相同的发票编号，也不会造成死锁。发票编号会在锁定期间分配；PDF 则在释放锁后生成，因此生成缓慢也不会阻塞编号计数器。保存时会先写入临时文件，再重命名到目标位置。

如果 schedules.json 或 history.json 无法读取或不是有效的 JSON，系统绝不会将其视为“空”：文件会逐字节移至旁边，命名为 <name>.json.corrupt-<timestamp>；同时会写入 <name>.json.corrupt 标记。在恢复有效副本并删除该标记之前，所有工具都会明确报错。这里尤其需要注意这一点：如果 history.json 被静默地读作空文件，计划涵盖过的所有周期都会再次扣款。

限制与如实说明

• 不会有任何内容在后台运行。 这是一个 stdio MCP 服务：它仅在客户端运行它时存在。没有守护进程、没有 cron、没有电子邮件。只有在你（或 monthly_billing_run 提示词）调用 invoice_generate_due 时，才会创建发票。auto_generate 是供该提示词使用的标记，不是调度器。
• 不会向客户端发送任何内容。 服务会生成发票记录和 PDF；发送发票和催款仍需由你处理。发票服务中的 overdue_report 会告诉你需要催收哪些款项。
• 免费套餐允许 3 个有效日程。暂停一个日程即可腾出名额；暂停日程的历史记录会保留。
• 删除日程会保留其历史记录，这是有意为之：使用相同 id 重新创建的日程无法对同一期间重复收费。这里的任何操作都不会触碰已生成的发票。
• schedule_update 只会更改未来期间。已经开具发票的期间仍保留已收取的金额；如需更正，请在发票服务中操作。
• 不按比例计费，也不为期间中途取消提供抵扣：一个期间要么全额计费，要么不计费。
• 不进行货币转换；一个日程只能使用一种货币计费。

故障排除

• npx 卡住或找不到软件包：此软件包仍在等待发布到 npm。在发布完成前，请使用 .mcpb 捆绑包或上文的克隆并构建方式。
• 使用克隆方式：先构建 servers/invoice，再构建 servers/recurring，因为后者会从前者导入引擎。npm run build -w packages/mcp-license -w servers/invoice -w servers/recurring 会按此顺序执行。
• “尚无业务资料”：请在发票服务（mcp-invoice）中运行 business_set，而不是在此处运行。生成操作不会因此受阻；PDF 只会使用占位发行方名称“Your business”。
• 发票不在我的发票服务中：两个服务必须使用相同的 XDG_DATA_HOME。它们会在该目录下的 .../mcp-servers/invoice/ 中写入数据；如果一个客户端设置了该变量，而另一个没有设置，你就会有两个数据存储。
• 某个期间被跳过了：invoice_generate_due 只会跳过 history.json 中已有记录的期间。schedule_history（Pro）或该文件会准确显示对应期间由哪张发票覆盖。
• Node 版本：需要 Node >= 18。使用 node -v 检查。

隐私

所有数据都保存在本地：日程、生成日志、发票和 PDF 都是你自己的主目录下的普通文件。该服务完全不会进行网络调用，许可证密钥也会离线验证。

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

整个套件共用一份业务资料

你的身份信息只存储一次，路径为 ${XDG_DATA_HOME:-~/.local/share}/mcp-servers/profile/business.json，套件中的每个服务都会读取它：发票发行方、docx 信头、周期性发行方、expense-tracker 的默认 VAT 税率、time-tracker 和 timezone 的主时区，以及简历和合同信头。使用 business_set（invoice 或 docx）设置一次即可，无需在其他地方重复设置。电子邮件地址只会取自该资料或明确提供的参数；如果资料中没有存储电子邮件地址，文档会显示 [add: email]，工具也会明确说明，而不会让任何人自行编造地址。

将这些文档用作 MCP 服务

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

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