recurring

mcp-recurring

「毎月1日に、Acmeに90 EURで12時間分を請求して」と一度伝えれば、覚えておく必要はありません。このMCPサーバーは、定期請求書のスケジュール、クライアント、明細、頻度、開始日と終了日を保存します。そして依頼すると、実際に支払期日を迎えた請求書を、請求書番号の連番、クライアント、A4 PDFを備えた請求書サーバーに実際のレコードとして作成します。生成処理は冪等です。発生予定日をキーとして、スケジュールごとに期間あたり1枚の請求書を作成するため、同じ日に請求処理を2回実行しても、2回目には何も作成されません。また、「今後30日間に何の支払期日が来るか」「来年は月ごとにいくら請求するか」にも答えます。すべてのデータはお使いのマシン上の通常のJSONファイルに保存され、外部にアップロードされることはありません。

公式MCPレジストリ に登録されています（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 バンドルを使うか、次の3つのコマンドだけでソースからビルドしてください。

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 がなく、管理するプロフィールを1つにするためです。
• mcp-time-tracker。定額契約に含まれない作業時間の管理に使えます。時間を記録し、必要に応じて請求書を作成し、毎月固定の分はここでスケジュール管理します。
• mcp-expense-tracker。月ごとに変動する再請求可能な費用は、その都度請求書を作成してください。スケジュールは、金額が変わらない項目向けです。

ツール

ツール	説明
schedule_create	繰り返し請求書を定義します：クライアント、品目、頻度、開始日、任意の終了日、支払期限までの日数、メモ
schedule_list	頻度、期間あたりの金額、次回の支払期日、ステータスを含むすべてのスケジュール
schedule_get	1つのスケジュールの全記録と、生成した請求書の数
schedule_update	クライアント、品目、通貨、頻度、日付、支払期限までの日数、またはメモを変更します。請求書発行済みの期間について、請求書が再発行されることはありません
schedule_pause	削除せずに生成を停止します。履歴は保持されます
schedule_resume	再び有効にします。一時停止中に支払期日を迎えた期間も、引き続き支払期日を過ぎた状態です
schedule_delete	スケジュールを削除します。生成済みの請求書は請求書サーバーに残り、監査証跡として履歴も保持されます。スケジュールを再作成すると新しい ID が割り当てられるため、invoice_generate_due は、以前のスケジュールですでに請求済みの期間を再度対象にした場合に警告します
schedule_skip	スケジュールを一時停止せずに、1回分を完全にスキップします。「10月はこのクライアントに請求しないで」という場合に使います。undo: true を指定すると、その期間を元に戻します
schedule_upcoming	今後 N 日以内に支払期日を迎える項目を、金額と通貨ごとの合計とともに表示します。また、すでに支払期日を過ぎていて、まだ請求書が発行されていない期間も表示します。無料版では30日分を対象にします
invoice_generate_due	指定日時点で支払期日を迎えている請求書を作成し、PDF を出力します。期間をキーとする冪等な処理で、作成数とスキップ数を報告します。1回の呼び出しにつき最大60件を古い期間から処理し、未処理の件数も表示します。dry_run では実行内容を事前に確認できます。無料で無制限に利用できます
schedule_history	Pro：1つのスケジュールの監査ログです。各期間、請求書番号、日付、金額、支払状況、PDF のパスを表示します
forecast	通貨ごとの暦月単位の予想収益を表示します。一時停止中のスケジュールは除外せず、別に一覧表示します。無料版では3か月分を対象にします
license_status	無料版か Pro 版かを表示します
license_activate	Pro キーを有効化します（オフラインで検証）

リソース：recurring://upcoming は、今後30日間の発生予定を JSON で返します。 プロンプト：monthly_billing_run は、ドライランを実行し、請求書を生成し、今後の予定を一覧表示してから、支払いリマインダーが必要な相手を報告します。

できること

指示の例	ツール
「Acme に毎月1日から、90 EUR で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 のリテイナー契約を1時間あたり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.

2回目の実行がポイントです。キーになるのは暦日ではなく期間なので、請求処理を繰り返しても何も起こらず、クライアントの受信トレイに重複した請求書が届くことはありません。

無料版と 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 = 1 ステップにつき +7 日です。{days: n} = 1 ステップにつき +n 日です。
• monthly = +1 か月、quarterly = +3 か月、yearly = +12 か月です。
• 月末。 月単位のステップでは start_date の日を維持し、対象月の日数に合わせて調整します。調整後の日付が次の月に引き継がれることはありません。2026-01-31 から始まる系列は、01-31、02-28、03-31、04-30、05-31 となります。2 月が、月末払いの契約をいつの間にか毎月 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 年に作成した毎日実行のスケジュールでも、1 日ずつ進んで実行ごとの発生回数上限に達することなく、2026 年の支払対象を報告できます。

金額

請求書エンジンと同じ ISO 4217 のテーブル、同じ「明細ごとに丸めてから合計する」仕様に従い、金額は整数の補助通貨単位で保持されます。そのため、スケジュールの金額と、そこから生成される請求書の金額が食い違うことはありません。各明細の総額を先に丸め、税額は明細ごとに計算して丸めたうえで税率ごとにまとめ、税率ごとに 1 つの明細にします。合計額は、すでに丸められた値を整数のまま合計します。スケジュールでは、設定された 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 が読み取るのも同じファイルです。

変更処理はすべて、アドバイザリーロックファイルの下で実行されます。請求書を書き込む処理は、必ず同じ順序で 2 つのロックを取得します。まず recurring/.lock、次に invoice/.lock です。そのため、2 つの請求処理同士、または請求処理と別サーバーで手書きした請求書の処理が同時に入り込むことや、同じ請求書番号を割り当てること、デッドロックが起きることはありません。請求書番号はロック中に割り当てられ、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 が変更するのは今後の期間のみです。すでに請求書が発行された期間には、請求済みの金額が保持されます。訂正は請求書サーバーで行ってください。
• 日割り計算や、期間途中の解約に対するクレジットはありません。期間の料金は全額請求されるか、まったく請求されないかのどちらかです。
• 通貨換算には対応していません。1 つのスケジュールで請求できる通貨は 1 種類です。

トラブルシューティング

• npx がハングする、またはパッケージが見つからない：このパッケージは npm への公開待ちです。公開されるまでは、.mcpb バンドルか、上記のクローンしてビルドする方法を使用してください。
• クローンする方法を使用する場合：エンジンを servers/invoice からインポートするため、servers/recurring より先に servers/invoice をビルドしてください。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/ に書き込まれます。一方のクライアントでその変数を設定し、もう一方で設定していない場合、保存先が 2 つに分かれます。
• 期間がスキップされた：invoice_generate_due が期間をスキップするのは、その期間が history.json にすでに存在する場合のみです。schedule_history（Pro）またはファイル自体を確認すると、その期間を対象とした請求書が正確に分かります。
• Node のバージョン：Node >= 18 が必要です。node -v で確認してください。

プライバシー

スケジュール、生成ログ、請求書、PDF など、すべてのデータはローカルに保存されます。これらはすべて、あなたのホームディレクトリ内にあるプレーンファイルです。サーバーはネットワーク通信を一切行わず、ライセンスキーはオフラインで検証されます。

theluckystrike が開発しました。MIT。サポート：[email protected]

スイート全体で使える 1 つのビジネスプロフィール

あなたの情報は ${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