MCP Server Ledger

🚀 mcp-server-ledger：Ledger CLIとのインタラクションを行うMCPサーバー

このプロジェクトは、Ledger CLIとのインタラクションを行うためのMCPサーバーです。大型言語モデルがLedger CLIを通じて財務データの照会や分析を行えるようにします。

🚀 クイックスタート

このMCPサーバーは、標準インターフェースを介してLedger CLIの機能を公開しており、AIアシスタントが財務報告、予算分析、会計業務を支援することができます。

✨ 主な機能

このサーバーは、以下のツールを提供しており、これらはLedger CLIコマンドにマッピングされています。

1. ledger_balance

   • 強力なフィルターオプション付きでアカウント残高を表示します。
   • 入力: クエリモード、日付範囲、表示オプション
   • 返却: フォーマットされた残高レポート

2. ledger_register

   • 詳細な取引記録を表示します。
   • 入力: クエリモード、日付範囲、ソートオプション
   • 返却: フォーマットされた登録レポート

3. ledger_accounts

   • 総勘定元帳ファイル内のすべてのアカウントをリストします。
   • 入力: オプションのクエリモード
   • 返却: 一致するアカウントのリスト

4. ledger_payees

   • 取引内のすべての支払人をリストします。
   • 入力: オプションのクエリモード
   • 返却: 一致する支払人のリスト

5. ledger_commodities

   • 使用されている商品（通貨）をリストします。
   • 入力: オプションのクエリモード
   • 返却: 一致する商品のリスト

6. ledger_print

   • 総勘定元帳形式で取引を印刷します。
   • 入力: クエリモード、日付範囲
   • 返却: フォーマットされた総勘定元帳エントリ

7. ledger_stats

   • 総勘定元帳ファイルに関する統計情報を表示します。
   • 入力: オプションのクエリモード
   • 返却: 総勘定元帳の要約統計情報

8. ledger_budget

   • 予算分析を表示します。
   • 入力: クエリモード、日付範囲、レポート周期
   • 返却: 予算レポート

9. ledger_raw_command

   • 生のLedger CLIコマンドを実行します。
   • 入力: コマンドパラメータを文字列リストとして
   • 返却: コマンド出力テキスト

📦 インストール

uvを使用する（推奨）

uvを使用すると、サーバーのインストールと実行が簡単です。

uv sync

📚 ドキュメント

設定

このサーバーでは、総勘定元帳ファイルのパスを指定する必要があります。以下の方法で指定できます。

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

Claude Desktopを使用する場合

以下の内容をclaude_desktop_config.jsonに追加してください。

"mcpServers": {
  "ledger": {
    "command": "uv server --listen tcp://0.0.0.0:1234 mcp-server-ledger@latest",
    "options": {
      "LEDGER_FILE": "/path/to/your-ledger-file.ledger"
    }
  }
}

💻 使用例

基本的な使用法

新しい総勘定元帳ファイルを作成する

uv run mcp-server-ledger@latest ledger --new /path/to/file.ledger

取引記録を追加する

uv run mcp-server-ledger@latest ledger --add " liabilities:bank" 1000 USD "Initial deposit"

アカウント残高を表示する

uv run mcp-server-ledger@latest ledger --balance assets

高度な使用法

サーバーをデバッグする

uv server --listen tcp://localhost:1234 mcp-server-ledger@latest --debug

ローカルで開発する

git clone git@github.com:minhyeoky/mcp-server-ledger.git
cd mcp-server-ledger
npm install

その後、開発サーバーを起動します。

uv server --listen tcp://localhost:1234 .

🔧 技術詳細

前提条件

• Ledger CLIがインストールされ、PATH環境変数が正しく設定されている必要があります。
• 有効な総勘定元帳ファイルが存在し、その中に財務データが含まれている必要があります。

📄 ライセンス

このソフトウェアはMITライセンスの下で保護されています。詳細についてはLICENSEを参照してください。

⚠️ 重要提示

機密性の高い財務データを不安全なネットワークに公開しないでください。また、総勘定元帳ファイルのセキュリティを確保し、不正アクセスを防止してください。