tuskledger-mcp

Tusk Ledger 用の Model Context Protocol サーバー。 AIアシスタントがローカルの個人財務データに型付きでアクセスできるようにします。データはマシン外に一切送信されません。

概要

ラップトップ上でローカルの Model Context Protocol サーバーとして動作する小さなPythonパッケージです。AIクライアント（Claude Desktop、Cursor、Cowork、Claude Codeなど、MCPに対応しているもの）の設定に追加すると、アシスタントが以下のようなツールを呼び出せるようになります：

• list_accounts — 残高と同期ステータスを含む接続済み口座の一覧

• query_transactions — 日付、口座、カテゴリなどでフィルタリング

• search_transactions — 加盟店やメモに対するあいまい検索

• get_spending_summary — 指定期間のカテゴリ別合計

• get_top_merchants — 最も支出の多い加盟店

• get_recurring_subscriptions — Netflixやジムなどの定期購読

• get_upcoming_bills — 今後30日間の請求と残高推移

• get_net_worth — 現在の純資産と12ヶ月の推移

• get_holdings — すべての投資ポジション

• get_investments_summary — ポートフォリオのまとめと資産配分

• get_retirement_projection — 保存されたシナリオに基づくモンテカルロ法による要約

• run_sync — Plaidの同期を実行

• list_stale_accounts — データが古い口座の一覧

サーバーは http://127.0.0.1:8000 でローカルのTusk Ledgerバックエンドと通信します。データはインターネットを通過しません。 「MCPクラウド」のようなものは存在せず、マシン上で実行されている1つのPythonプロセスが、同じマシン上の別のPythonプロセスと通信するだけです。

なぜこれが必要なのか

Tusk Ledger は、エージェントを活用するユーザーのために構築されています。5年前には一人ではできなかったことを、Claude / Cursor / Cowork に依頼できるユーザーのためのものです。このMCPサーバーは、その目標に向けた最も強力な手段です。アシスタントは、React UIをスクレイピングしたりデータベーススキーマを推測したりする必要がなく、財務データに型付きの構造化されたアクセスが可能になります。

インストール後の活用例：

• 「Whole Foodsでの過去6ヶ月の取引を『ショッピング』ではなく『食料品』に分類して。」 → アシスタントがクエリを実行し、あなたが確認した上でルールを作成します。

• 「先四半期にコーヒーにいくら使った？」 → UIをクリックすることなく、3秒で回答します。

• 「今朝、純資産が減ったんだけど、原因は何？」 → アシスタントが口座、残高、最近の取引を取得して診断します。

• 「今年、HSAの拠出限度額に到達できそう？」 → HSAの残高、年初来の拠出額、IRSの制限額を読み取り、不足分を返します。

前提条件

• 実行中の Tusk Ledger インストール（メインアプリ）

• Python 3.10以上

• MCP対応クライアント（Claude Desktop、Cursor、Cowork、Claude Codeなど）

インストール

オプションA — uvx（推奨、永続的なインストール不要）

uv (pip install uv) がインストールされている場合：

// In your MCP client's config
{
  "mcpServers": {
    "tuskledger": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/BradMorphsters/tuskledger-mcp", "tuskledger-mcp"]
    }
  }
}

uvx が分離されたPython環境を処理するため、グローバルなPython環境を汚染しません。サーバーは初回実行時に取得・キャッシュされます。

オプションB — GitHubから pip install

pip install git+https://github.com/BradMorphsters/tuskledger-mcp

その後、MCPクライアントでインストールされた tuskledger-mcp バイナリを指定します：

{
  "mcpServers": {
    "tuskledger": {
      "command": "tuskledger-mcp"
    }
  }
}

（venvを使用している場合は which tuskledger-mcp で得られるフルパスを使用してください。）

オプションC — 開発用にクローン

git clone https://github.com/BradMorphsters/tuskledger-mcp
cd tuskledger-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e .

MCPクライアントの設定ファイルの場所

設定を編集した後、クライアントを再起動してください。サーバーはクライアントの起動時に立ち上がり、終了時に停止します。

設定

2つの環境変数が利用可能です（どちらもオプション）：

例：

{
  "mcpServers": {
    "tuskledger": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/BradMorphsters/tuskledger-mcp", "tuskledger-mcp"],
      "env": {
        "TUSKLEDGER_BASE_URL": "http://127.0.0.1:8000",
        "TUSKLEDGER_TIMEOUT_SECONDS": "30"
      }
    }
  }
}

認証

このv0バージョンでは、Tusk Ledgerバックエンドが DEV_BYPASS_AUTH=true で実行されていることを前提としています（メインリポジトリのREADMEに記載されている一般的なシングルマシン構成）。認証を有効にしたままにしている場合、MCPサーバーの呼び出しは401エラーで失敗し、アシスタントの応答にエラーが表示されます。

認証対応はロードマップに含まれています。それまでの間、認証とMCPの両方を使用したい場合は、アシスタントを使用している間だけ DEV_BYPASS_AUTH=true でバックエンドを実行し、終わったら元に戻してください。

このサーバーが意図的に行わないこと

設計上、v0は読み取り専用です。サーバーは以下を公開しません：

• 口座、取引、ルール、目標の削除

• データベーススキーマの変更やマイグレーションの実行

• 認証の無効化や暗号化キーのローテーション

• Plaidアクセストークンの操作

• 127.0.0.1 以外の場所へのデータ送信

その理由は、AIアシスタントはデータの理解や安全な操作（同期、クエリ）を支援すべきであり、不可逆的な変更はWeb UIで行うべきだからです。将来のバージョンで、明示的な確認フローを伴う構造化された書き込みツール（例：「ルールを作成する」）を追加する可能性がありますが、基準は高く保たれます。

トラブルシューティング

Could not reach Tusk Ledger backend at http://127.0.0.1:8000 — Tusk Ledgerアプリが実行されていません。メインリポジトリから ./start.sh を実行してください。

401 Unauthorized — 認証が有効になっています。上記の「認証」セクションを参照してください。今のところは DEV_BYPASS_AUTH=true で実行してください。

404 Not Found — バックエンドにアクセスしようとしているエンドポイントが存在しません。Tusk Ledgerのバージョンが古い可能性があります。メインアプリを更新し、MCPクライアントを再起動してください。

ツールがアシスタントに表示されない — MCPサーバーの起動に失敗しています。クライアントのMCPサーバーログを確認してください（Claude Desktopには「View MCP server logs」メニュー項目があります）。一般的な原因：設定のパスが間違っている、PythonがPATHに含まれていない、uvx がインストールされていないなど。

一般的なヘルスチェック — メインのTusk Ledgerリポジトリから ./tuskledger doctor を実行してください。これがインストール全体の標準的な診断ツールです。

開発

git clone https://github.com/BradMorphsters/tuskledger-mcp
cd tuskledger-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e .
pip install pytest pytest-asyncio
pytest tests/ -v

テストはMCPトランスポートを立ち上げず、モッククライアントを使用してディスパッチレイヤーを直接実行します。MCPプロトコル自体は単なるラッパーです。

CIはGitHub Actionsを通じてPython 3.10/3.11/3.12で同じスイートを実行します（.github/workflows/ci.yml を参照）。

プロジェクトリンク

• メインアプリ: https://github.com/BradMorphsters/tuskledger

• プロジェクトサイト: https://www.tuskledger.com

• 外部から閲覧するエージェント向け: https://www.tuskledger.com/llms.txt

• イシュー / ディスカッション: https://github.com/BradMorphsters/tuskledger-mcp/issues

• ライセンス: MIT