mcp-server-ledger: A Ledger CLI MCP Server

mcp-server-ledger：Ledger CLI MCP サーバー

概要

コマンドラインから利用できる強力な複式簿記システムである Ledger CLI と連携するための Model Context Protocol サーバーです。このサーバーを使うと、LLM は Ledger CLI ツールを通じて財務データを照会、分析できます。

この MCP サーバーは Ledger CLI の機能を標準化されたインターフェースを通じて公開するため、AI アシスタントが財務レポート、予算分析、会計業務を簡単に支援できます。

機能

このサーバーは、Ledger CLI コマンドに対応する次のツールを提供します。

1. ledger_balance

   • 強力なフィルタリングオプションで口座残高を表示します
   • 入力：クエリパターン、日付範囲、表示オプション
   • 戻り値：書式設定された残高レポート

2. ledger_register

   • 詳細な履歴を含む取引明細を表示します
   • 入力：クエリパターン、日付範囲、並べ替えオプション
   • 戻り値：書式設定された明細レポート

3. ledger_accounts

   • Ledger ファイル内のすべての口座を一覧表示します
   • 入力：任意のクエリパターン
   • 戻り値：一致する口座の一覧

4. ledger_payees

   • 取引に含まれるすべての受取人を一覧表示します
   • 入力：任意のクエリパターン
   • 戻り値：一致する受取人の一覧

5. ledger_commodities

   • 使用されているすべての商品（通貨）を一覧表示します
   • 入力：任意のクエリパターン
   • 戻り値：一致する商品の一覧

6. ledger_print

   • Ledger 形式で取引を出力します
   • 入力：クエリパターン、日付範囲
   • 戻り値：書式設定された Ledger エントリ

7. ledger_stats

   • Ledger ファイルに関する統計を表示します
   • 入力：任意のクエリパターン
   • 戻り値：Ledger の統計概要

8. ledger_budget

   • 予算分析を表示します
   • 入力：クエリパターン、日付範囲、レポート期間
   • 戻り値：予算レポート

9. ledger_raw_command

   • Ledger CLI の生コマンドを実行します
   • 入力：文字列のリストとしてのコマンド引数
   • 戻り値：コマンドの出力テキスト

前提条件

• Ledger CLI がインストールされ、PATH から利用できること
• 財務データを含む有効な Ledger ファイル

インストール

Docker を使用する（推奨）

minhyeoky/mcp-ledger リポジトリの Docker イメージも使用できます。

docker pull minhyeoky/mcp-ledger

これを claude_desktop_config.json に追加します。

"mcp-ledger": {
  "command": "docker",
  "args": [
    "run",
    "-v",
    "/path/to/your/ledger/file.ledger:/main.ledger",
    "-e",
    "LEDGER_FILE=/main.ledger",
    "-i",
    "--rm",
    "minhyeoky/mcp-ledger"
  ]
}

/path/to/your/ledger/file.ledger を実際の Ledger ファイルのパスに置き換えてください。

Smithery 経由でインストールする

Smithery を使って、Claude Desktop 用の Ledger CLI MCP Server を自動的にインストールするには、次のコマンドを実行します。

npx -y @smithery/cli install @minhyeoky/mcp-ledger --client claude

uv を使用する

このサーバーをインストールして実行する最も簡単な方法は、uv を使うことです。

uv sync

設定

このサーバーには Ledger ファイルのパスが必要です。次の方法で指定できます。

• LEDGER_FILE 環境変数
• サーバーの起動時に指定するコマンドライン引数

Claude Desktop で使用する

これを claude_desktop_config.json に追加します。

"mcpServers": {
  "ledger": {
    "command": "uv",
    "args": [
      "run",
      "--env-file",
      "/path/to/your/.env",  // Optional: to set LEDGER_FILE
      "--with",
      "mcp[cli]",
      "mcp",
      "run",
      "<repo_path>/main.py"  // Path to the main.py file in this repository
    ]
  }

}

使用例

設定が完了したら、財務データについて AI アシスタントに質問できます。

• 「先月の支出を見せて」
• 「すべての口座の現在の残高は？」
• 「Amazon との取引をすべて一覧表示して」
• 「2023 年に食料品にいくら使った？」
• 「第 1 四半期の予算実績を見せて」

AI はサーバーを通じて適切な Ledger CLI コマンドを使用し、情報を取得します。

デバッグ

ローカルでより詳細なテストを行うには、次を実行します。

mcp dev main.py

開発

このサーバーはModel Context Protocol Python SDKを使用して構築されています。MCP と MCP サーバーの開発方法について詳しくは、公式ドキュメントをご覧ください。

このプロジェクトに貢献するには：

1. リポジトリをクローンします
2. 開発用の依存関係をインストールします
3. 変更を加えます
4. MCP inspector を使用するか、Claude Desktop と統合してテストします

セキュリティに関する考慮事項

このサーバーは、財務データに対して Ledger CLI コマンドを実行します。コマンドインジェクションを防ぐための基本的な検証を備えていますが、次の点にご注意ください。

• 信頼できるクライアントとのみ使用してください
• 公開するファイルパスには注意してください
• 実行前にすべてのコマンドを確認してください

ライセンス

この MCP サーバーは MIT License の下でライセンスされています。ライセンス条項に従って、自由に使用、変更、配布できます。