Actual MCP

🚀 Actual Budget MCP Server

Actual Budget MCPサーバーは、Actual BudgetとClaudeやその他のLLMアシスタントを統合するためのサーバーです。自然言語を通じて、個人の財務データと対話できるようにします。

🚀 クイックスタート

Actual Budget MCPサーバーを使用することで、Actual Budgetの個人財務データをLLMを通じて自然言語で操作できます。このサーバーは、Model Context Protocol (MCP) を介してアカウント、取引、財務指標を公開します。

✨ 主な機能

リソース

• アカウント一覧 - 残高を含むすべてのアカウントを閲覧できます。
• アカウント詳細 - 特定のアカウントに関する詳細情報を表示します。
• 取引履歴 - 完全な詳細を含む取引データにアクセスできます。

ツール

• get-transactions - アカウント、日付、金額、カテゴリ、または支払い先で取引を取得およびフィルタリングします。
• spending-by-category - タイプ別に分類された支出内訳を生成します。
• monthly-summary - 月次の収入、支出、および貯蓄指標を取得します。
• balance-history - 時間の経過に伴うアカウント残高の変化を表示します。

プロンプト

• financial-insights - 財務データに基づいて洞察と推奨事項を生成します。
• budget-review - 予算遵守状況を分析し、調整案を提案します。

📦 インストール

前提条件

• Node.js (v16以上)
• Actual Budget がインストールされ、設定されていること
• Claude Desktop またはその他のMCP互換クライアント

セットアップ

1. リポジトリをクローンします。

git clone https://github.com/s-stefanov/actual-mcp.git
cd actual-mcp

2. 依存関係をインストールします。

npm install

3. サーバーをビルドします。

npm run build

4. 環境変数を設定します（オプション）。

# Actual Budgetデータディレクトリへのパス（デフォルト: ~/.actual）
export ACTUAL_DATA_DIR="/path/to/your/actual/data"

# リモートのActualサーバーを使用する場合
export ACTUAL_SERVER_URL="https://your-actual-server.com"
export ACTUAL_PASSWORD="your-password"

# 使用する特定の予算（オプション）
export ACTUAL_BUDGET_SYNC_ID="your-budget-id"

💻 使用例

基本的な使用法

Claude Desktopでこのサーバーを使用するには、Claudeの設定に追加します。

MacOSの場合:

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

Windowsの場合:

code %APPDATA%\Claude\claude_desktop_config.json

設定に以下を追加します。

{
  "mcpServers": {
    "actualBudget": {
      "command": "npx",
      "args": ["-y", "actual-mcp"],
      "env": {
        "ACTUAL_DATA_DIR": "/path/to/your/actual/data",
        "ACTUAL_PASSWORD": "your-password",
        "ACTUAL_SERVER_URL": "https://your-actual-server.com",
        "ACTUAL_BUDGET_SYNC_ID": "your-budget-id"
      }
    }
  }
}

{
  "mcpServers": {
    "actualBudget": {
      "command": "docker",
      "args": ["run", "-it", "--rm", "-p", "3000:3000", "sstefanov/actual-mcp:latest"],
      "env": {
        "ACTUAL_DATA_DIR": "/path/to/your/actual/data",
        "ACTUAL_PASSWORD": "your-password",
        "ACTUAL_SERVER_URL": "https://your-actual-server.com",
        "ACTUAL_BUDGET_SYNC_ID": "your-budget-id"
      }
    }
  }
}

設定を保存したら、Claude Desktopを再起動します。

接続後、Claudeに以下のような質問をすることができます。

• "現在のアカウント残高はいくらですか？"
• "先月のカテゴリ別支出を表示してください"
• "1月に食料品にいくら使いましたか？"
• "過去3か月間の貯蓄率はいくらですか？"
• "予算を分析し、改善すべき分野を提案してください"

高度な使用法

開発時に自動再構築を行うには、以下のコマンドを実行します。

npm run watch

Actualへの接続をテストするには、以下のコマンドを実行します。

node build/index.js --test-resources

MCPサーバーはstdioを介して通信するため、デバッグは難しい場合があります。MCP Inspector を使用することができます。

npx @modelcontextprotocol/inspector node build/index.js

📚 ドキュメント

プロジェクト構造

• index.ts - メインサーバーの実装
• types.ts - APIレスポンスとパラメータの型定義
• prompts.ts - LLMとの対話用のプロンプトテンプレート
• utils.ts - 日付フォーマットなどのヘルパー関数

📄 ライセンス

このプロジェクトはMITライセンスの下で公開されています。

コントリビューション

コントリビューションは大歓迎です！プルリクエストを送信してください。