Hledger MCP

🚀 HLedger MCP Server

このModel Context Protocol (MCP) サーバーは、AIアシスタント (MCPクライアント) に HLedger の会計データと機能への直接アクセスを提供します。このサーバーにより、AIアプリケーションは標準化されたプロトコルを通じて、口座残高の照会、財務報告の生成、新しいエントリの追加、会計データの分析などを行うことができます。

🚀 クイックスタート

HLedger MCPサーバーは、AIアシスタントにHLedgerの会計データと機能への直接アクセスを提供します。以下の手順ですぐに始めることができます。

前提条件

• HLedger がシステムのPATHにインストールされ、アクセス可能であること。
  • hledger.org からインストールします。
  • インストールを確認するには、hledger --version を実行します。
• Node.js v18以上

インストールと設定

Claude Desktopの設定

• .mcpbファイルのインストール：リリース から提供される .mcpb ファイルを使用するのが最も簡単です。npmを好む場合は、以下の方法を使用できます。
• npmを使用したインストール：Claude Desktopの設定ファイルに以下の内容を追加します。
  • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows：%APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "hledger": {
      "command": "npx",
      "args": ["-y", "@iiatlas/hledger-mcp", "/path/to/your/master.journal"]
    }
  }
}

/path/to/your/master.journal を実際のHLedgerジャーナルファイルのパスに置き換えてください。

その他のMCPクライアント

他のMCP互換アプリケーションの場合は、以下のコマンドでサーバーを起動します。

npx @iiatlas/hledger-mcp /path/to/your/master.journal

✨ 主な機能

HLedger MCPサーバーは、以下のツールを通じて、HLedgerの財務報告機能への包括的なアクセスを提供します。

コア会計機能

• 口座：口座名と構造の一覧表示と照会
• 残高：高度なカスタマイズオプションで残高報告を生成
• レジスター：取引レジスターとポスティング詳細を表示
• 印刷：ジャーナルエントリと取引を出力

財務報告

• 貸借対照表：貸借対照表報告を生成
• 貸借対照表（エクイティ詳細付き）：エクイティ詳細を含む貸借対照表報告
• 損益計算書：損益計算書
• キャッシュフロー：キャッシュフロー分析と報告

データ分析

• 統計：ジャーナルデータの統計分析
• アクティビティ：口座アクティビティと取引頻度の分析
• 支払先：取引支払先の一覧表示と分析
• 説明：取引説明の分析
• タグ：取引タグの照会と分析
• メモ：一意の取引メモとメモフィールドの一覧表示
• ファイル：hledgerが使用するデータファイルの一覧表示

リソース統合

• メインのジャーナルと hledger files が報告するすべてのファイルを自動的にMCPリソースとして登録し、クライアントがソース元帳を閲覧および取得できるようにします。

ジャーナル更新

• 取引の追加：新しい、検証済みのジャーナルエントリを追加し、オプションでドライランをサポート
• エントリの検索：任意のhledgerクエリに一致する完全な取引（ファイルと行のメタデータ付き）を検索
• エントリの削除：正確なテキストと位置を使用して取引を安全に削除し、オプションでドライランをサポート
• エントリの置換：変更を検証した後、既存の取引を新しい内容に置き換える
• 取引のインポート：外部のジャーナルファイルまたは他のサポートされる形式から取引を安全に取り込む
• 決算：決算/開帳、剰余金、またはアサーション取引を生成し、安全に追加する
• 取引の書き換え：hledgerの書き換えコマンドを使用して、一致するエントリに合成ポスティングを追加する

Webインターフェイス

MCPサーバー内で直接hledgerのWeb UIを開くことができます！

• Webの起動：MCPサーバーをブロックせずに、要求されたモードで hledger web を起動します。
  • オプションの hledger-web 実行可能ファイルが必要です。hledger バイナリが web コマンドを認識しない場合は、hledger-web をインストールするか（多くの場合、別のパッケージとして提供されます）、Webサポート付きでビルドされた実行可能ファイルをMCPサーバーに指定してください。
  • HLEDGER_WEB_EXECUTABLE_PATH を設定すると、MCPサーバーがWebインターフェイスを起動するために専用のバイナリ（例：hledger-web）を使用します。
• Webインスタンスの一覧表示/停止：セッション中に起動されたすべての実行中のWebサーバーを列挙し、1つまたはすべてを正常に終了させます。

読み取り専用のMCPセッションでは、常にWebインターフェイスを view モードで実行します。書き込み可能なセッションでは、明示的に allow: "edit" が要求されない限り、デフォルトで add 権限が設定されます。

💻 使用例

基本的な使用法

Claude Desktopを使用する場合、設定後に自然言語で財務データに関する質問をすることができます。

# 以下は質問の例
- "What's my current account balance?"
- "Show me a balance sheet for last quarter"
- "What were my expenses in the food category last month?"
- "Generate an income statement for 2024"
- "Who are my top payees by transaction volume?"
- "Show me cash flow for the past 6 months"

高度な使用法

サーバーを起動し、各種ツールを使用してジャーナルの更新やWebインターフェイスの操作を行うことができます。

# サーバーの起動
npx @iiatlas/hledger-mcp /path/to/your/master.journal

# 取引の追加
hledger_add_transaction --structured-postings ...

# Web UIの起動
hledger_web

📚 ドキュメント

ツールパラメータ

ほとんどのツールは、以下の一般的なHLedgerオプションをサポートしています。

• 日付範囲：--begin, --end, --period
• 出力形式：txt, csv, json, html
• 口座フィルタリング：パターンマッチングと正規表現のサポート
• 計算モード：履歴、累積、変更分析
• 表示オプション：フラット表示とツリー表示、ソート、パーセンテージ表示

開発

ソースからのビルド

# リポジトリをクローン
git clone <repository-url>
cd hledger-mcp

# (オプション) nvmを持っている場合は、このバージョンを使用
nvm use

# 依存関係をインストール
npm install

# サーバーをビルド
npm run build

# テスト
npm run test

# デバッグサーバーを実行
npm run debug

プロジェクト構造

src/
├── index.ts              # メインサーバーのエントリポイント
├── base-tool.ts          # 基本的なツールクラスとユーティリティ
├── executor.ts           # コマンド実行ユーティリティ
├── journal-writer.ts     # 安全なジャーナル書き込み操作
├── resource-loader.ts    # MCPリソースの探索とロード
├── types.ts              # 共有型定義
└── tools/                # 個々のツールの実装
    ├── accounts.ts       # 口座名と構造の一覧表示
    ├── activity.ts       # 口座アクティビティ分析
    ├── add.ts            # 新しい取引の追加
    ├── balance.ts        # 残高報告
    └── ...               # ...およびその他多数

test/
├── resources/            # テスト用のジャーナルファイル
│   ├── master.journal    # インクルード付きのサンプルマスタージャーナル
│   ├── 01-jan.journal    # 月次ジャーナルファイル
│   ├── 02-feb.journal
│   └── ...
├── *.test.ts            # ツールとユーティリティの単体テスト
└── ...

トラブルシューティング

"hledger CLI is not installed"

HLedgerがインストールされ、PATHに含まれていることを確認します。

hledger --version

hledger CLIのパスは、一般的な場所で自動的に検索されます（hledger-path.ts:8 を参照）。自動検索が機能しない場合は、HLEDGER_EXECUTABLE_PATH 環境変数にパスを設定することができます。

# hledgerのインストールパスを検索
which hledger

"hledger web command is failing"

すべてのhledgerインスタンスに hledger-web バイナリが含まれているわけではありません。また、一部のインストール方法（例：.mcpb）では、このバイナリを見つけるのが困難な場合があります。Web UIの起動に問題がある場合は、まずインストールまたは現在のインストール場所を見つけてください。

# hledger-webのインストールパスを検索
which hledger-web

その後、環境変数に設定します。Homebrewを使用してインストールした場合は、以下のようになります。

HLEDGER_WEB_EXECUTABLE_PATH=/opt/homebrew/bin/hledger-web

"Journal file path is required"

サーバーは引数としてジャーナルファイルのパスを必要とします。設定を確認し、有効なパスが含まれていることを確認してください。

Claude Desktop接続問題

1. ジャーナルファイルのパスが正しく、アクセス可能であることを確認します。
2. 設定ファイルの構文が有効なJSONであることを確認します。
3. 設定を変更した後、Claude Desktopを再起動します。

📄 ライセンス

MITライセンス（LICENSE を参照）

関連プロジェクト

• HLedger - 基盤となる会計ソフトウェア
• Model Context Protocol - プロトコル仕様
• Claude Desktop - MCPサーバーをサポートするAIアシスタント