mcpField
C
cli-anything-firefly-iii

cli-anything-firefly-iii

github.com/hkudsその他57.6k355 回インストール5 週間前に更新
リポジトリ

cli-anything-firefly-iii について

cli-anything-firefly-iiiは、API経由でFirefly IIIを管理するステートレスなコマンドラインツールです。金融記録、予算、レポート、自動化などを扱い、スクリプトやエージェントワークフロー向けにJSON出力とコマンドプリセットを備えています。

主な機能

  1. 01口座と取引の管理
  2. 02予算、請求、カテゴリの管理
  3. 03ルール、定期取引、Webhookの管理
  4. 04検索、エクスポート、レポート表示
  5. 05プリセットによるコマンド絞り込み
  6. 06構造化JSON出力

活用シーン

  1. 01支出の記録と口座残高の確認
  2. 02収支レポートの作成
  3. 03ルールや定期取引による処理の自動化
  4. 04JSON出力を使ったFirefly III操作のスクリプト化

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/hkuds/cli-anything --skill cli-anything-firefly-iii

インストール後、Claude Code で/cli-anything-firefly-iiiを入力して読み込まれたか確認します。

詳細

Firefly III CLI

CLI-Anything 仕様に基づく Firefly III コマンドラインインターフェースです。MCP モードをステートレスな CLI モードに変換し、Node の残留プロセスの問題を回避します。

インストール

pip install cli-anything-firefly-iii

前提条件

  • Python 3.10 以上
  • 実行中の Firefly III インスタンス
  • パーソナルアクセストークン（PAT）

設定

環境変数（推奨）
export FIREFLY_III_BASE_URL="https://firefly.yourdomain.com"
export FIREFLY_III_PAT="your-personal-access-token"
コマンドライン引数
cli-anything-firefly-iii --base-url https://firefly.yourdomain.com --pat your-token

コマンドグループ

コマンドグループ説明対応する API
accounts口座管理（CRUD）/api/v1/accounts
transactions取引管理（CRUD）/api/v1/transactions
budgets予算管理（CRUD + 上限）/api/v1/budgets
categoriesカテゴリ管理（CRUD）/api/v1/categories
tagsタグ管理（CRUD）/api/v1/tags
bills請求書管理（CRUD）/api/v1/bills
piggy-banks貯金箱管理（CRUD + イベント）/api/v1/piggy-banks
autocomplete各種エンティティのオートコンプリート/api/v1/autocomplete/*
currencies通貨管理（CRUD）/api/v1/currencies
recurrences定期取引管理（CRUD）/api/v1/recurrences
rulesルール管理（CRUD + テスト/実行）/api/v1/rules
rule-groupsルールグループ管理（CRUD + 実行）/api/v1/rule-groups
summary財務サマリー/api/v1/summary/*
webhooksWebhook 管理（CRUD + トリガー）/api/v1/webhooks
insightsインサイトとレポート/api/v1/insight/*
search検索/api/v1/search/*
exportデータエクスポート/api/v1/data/export/*
infoシステム情報/api/v1/about

使用例

口座管理
# List all accounts
cli-anything-firefly-iii --json accounts list

# List asset accounts
cli-anything-firefly-iii --json accounts list --type asset

# Get account details
cli-anything-firefly-iii --json accounts get --id 123

# Create account
cli-anything-firefly-iii --json accounts create --name "Cash" --type asset --currency-code USD

# Update account
cli-anything-firefly-iii --json accounts update --id 123 --name "New Name"

# Delete account
cli-anything-firefly-iii accounts delete --id 123
取引管理
# List transactions
cli-anything-firefly-iii --json transactions list --limit 10

# List transactions with date range
cli-anything-firefly-iii --json transactions list --start 2024-01-01 --end 2024-01-31

# Create transaction
cli-anything-firefly-iii --json transactions create \
  --description "Grocery" \
  --amount 50.00 \
  --source-account 1 \
  --category "Food"

# Update transaction
cli-anything-firefly-iii --json transactions update --id 456 --description "Updated"

# Delete transaction
cli-anything-firefly-iii transactions delete --id 456
予算管理
# List budgets
cli-anything-firefly-iii --json budgets list

# Get budget details
cli-anything-firefly-iii --json budgets get --id 1

# Create budget
cli-anything-firefly-iii --json budgets create --name "Monthly Budget"

# Update budget
cli-anything-firefly-iii --json budgets update --id 1 --name "New Budget Name"

# Delete budget
cli-anything-firefly-iii budgets delete --id 1

# List budget limits
cli-anything-firefly-iii --json budgets limits --budget-id 1

# Create budget limit
cli-anything-firefly-iii --json budgets limit-create --budget-id 1 --amount 1000 --start 2024-01-01 --end 2024-01-31

# Update budget limit
cli-anything-firefly-iii --json budgets limit-update --id 1 --amount 1500

# Delete budget limit
cli-anything-firefly-iii budgets limit-delete --id 1
カテゴリ管理
# List categories
cli-anything-firefly-iii --json categories list

# Get category
cli-anything-firefly-iii --json categories get --id 1

# Create category
cli-anything-firefly-iii --json categories create --name "Food"

# Update category
cli-anything-firefly-iii --json categories update --id 1 --name "Food & Dining"

# Delete category
cli-anything-firefly-iii categories delete --id 1
タグ管理
# List tags
cli-anything-firefly-iii --json tags list

# Get tag
cli-anything-firefly-iii --json tags get --id "uuid-here"

# Create tag
cli-anything-firefly-iii --json tags create --tag "important"

# Update tag
cli-anything-firefly-iii --json tags update --id "uuid-here" --tag "important-updated"

# Delete tag
cli-anything-firefly-iii tags delete --id "uuid-here"
請求書管理
# List bills
cli-anything-firefly-iii --json bills list

# Get bill
cli-anything-firefly-iii --json bills get --id 1

# Create bill
cli-anything-firefly-iii --json bills create \
  --name "Netflix" \
  --amount-min 15.99 \
  --amount-max 15.99 \
  --frequency monthly

# Update bill
cli-anything-firefly-iii --json bills update --id 1 --amount-min 19.99

# Delete bill
cli-anything-firefly-iii bills delete --id 1
貯金箱管理
# List piggy banks
cli-anything-firefly-iii --json piggy-banks list

# Get piggy bank
cli-anything-firefly-iii --json piggy-banks get --id 1

# Create piggy bank
cli-anything-firefly-iii --json piggy-banks create \
  --name "Vacation Fund" \
  --account-id 1 \
  --target-amount 5000

# Update piggy bank
cli-anything-firefly-iii --json piggy-banks update --id 1 --name "New Name"

# Delete piggy bank
cli-anything-firefly-iii piggy-banks delete --id 1

# List piggy bank events
cli-anything-firefly-iii --json piggy-banks events --id 1

# Add money to piggy bank
cli-anything-firefly-iii --json piggy-banks add-money --id 1 --amount 100
オートコンプリート
# Autocomplete accounts
cli-anything-firefly-iii --json autocomplete accounts --query "bank"

# Autocomplete categories
cli-anything-firefly-iii --json autocomplete categories --query "food"

# Autocomplete tags
cli-anything-firefly-iii --json autocomplete tags --query "important"

# Autocomplete transactions
cli-anything-firefly-iii --json autocomplete transactions --query "grocery"

# Autocomplete budgets
cli-anything-firefly-iii --json autocomplete budgets --query "monthly"

# Autocomplete bills
cli-anything-firefly-iii --json autocomplete bills --query "netflix"

# Autocomplete piggy banks
cli-anything-firefly-iii --json autocomplete piggy-banks --query "vacation"

# Autocomplete currencies
cli-anything-firefly-iii --json autocomplete currencies --query "dollar"

# Autocomplete rules
cli-anything-firefly-iii --json autocomplete rules --query "auto"

# Autocomplete rule groups
cli-anything-firefly-iii --json autocomplete rule-groups --query "finances"

# Autocomplete recurring
cli-anything-firefly-iii --json autocomplete recurring --query "rent"

# Autocomplete object groups
cli-anything-firefly-iii --json autocomplete object-groups --query "group"

# Autocomplete transaction types
cli-anything-firefly-iii --json autocomplete transaction-types --query "with"
通貨管理
# List currencies
cli-anything-firefly-iii --json currencies list

# Get currency
cli-anything-firefly-iii --json currencies get --id 1

# Create currency
cli-anything-firefly-iii --json currencies create \
  --code "CNY" \
  --name "Chinese Yuan" \
  --symbol "¥"

# Update currency
cli-anything-firefly-iii --json currencies update --id 1 --symbol "元"

# Delete currency
cli-anything-firefly-iii currencies delete --id 1

# Get exchange rates
cli-anything-firefly-iii --json currencies exchange-rates --from USD --to EUR
定期取引管理
# List recurring transactions
cli-anything-firefly-iii --json recurrences list

# Get recurring transaction
cli-anything-firefly-iii --json recurrences get --id 1

# Create recurring transaction
cli-anything-firefly-iii --json recurrences create \
  --title "Rent Payment" \
  --type withdrawal \
  --amount 1500 \
  --source-account 1 \
  --destination-account 2 \
  --frequency monthly

# Update recurring transaction
cli-anything-firefly-iii --json recurrences update --id 1 --amount 1600

# Delete recurring transaction
cli-anything-firefly-iii recurrences delete --id 1
ルール管理
# List rules
cli-anything-firefly-iii --json rules list

# Get rule
cli-anything-firefly-iii --json rules get --id 1

# Create rule
cli-anything-firefly-iii --json rules create \
  --title "Auto-tag groceries" \
  --trigger "description_contains" \
  --value "grocery" \
  --action set_category \
  --action-value "Food"

# Update rule
cli-anything-firefly-iii --json rules update --id 1 --title "New Title"

# Delete rule
cli-anything-firefly-iii rules delete --id 1

# Test rule
cli-anything-firefly-iii --json rules test --id 1

# Execute rule
cli-anything-firefly-iii --json rules execute --id 1
ルールグループ管理
# List rule groups
cli-anything-firefly-iii --json rule-groups list

# Get rule group
cli-anything-firefly-iii --json rule-groups get --id 1

# Create rule group
cli-anything-firefly-iii --json rule-groups create --title "Finance Rules"

# Update rule group
cli-anything-firefly-iii --json rule-groups update --id 1 --title "New Title"

# Delete rule group
cli-anything-firefly-iii rule-groups delete --id 1

# Execute rule group
cli-anything-firefly-iii --json rule-groups execute --id 1
サマリーレポート
# Default summary set
cli-anything-firefly-iii --json summary default-set --start 2024-01-01 --end 2024-01-31

# Account summary
cli-anything-firefly-iii --json summary account-summary --start 2024-01-01 --end 2024-01-31

# Available budget summary
cli-anything-firefly-iii --json summary available-budget --start 2024-01-01 --end 2024-01-31

# Bill summary
cli-anything-firefly-iii --json summary bill-summary --start 2024-01-01 --end 2024-01-31

# Budget summary
cli-anything-firefly-iii --json summary budget-summary --start 2024-01-01 --end 2024-01-31

# Category summary
cli-anything-firefly-iii --json summary category-summary --start 2024-01-01 --end 2024-01-31

# Tag summary
cli-anything-firefly-iii --json summary tag-summary --start 2024-01-01 --end 2024-01-31

# Transfer summary
cli-anything-firefly-iii --json summary transfer-summary --start 2024-01-01 --end 2024-01-31
Webhook 管理
# List webhooks
cli-anything-firefly-iii --json webhooks list

# Get webhook
cli-anything-firefly-iii --json webhooks get --id 1

# Create webhook
cli-anything-firefly-iii --json webhooks create \
  --title "My Webhook" \
  --trigger create \
  --url "https://example.com/webhook" \
  --secret "my-secret"

# Update webhook
cli-anything-firefly-iii --json webhooks update --id 1 --title "New Title"

# Delete webhook
cli-anything-firefly-iii webhooks delete --id 1

# Trigger webhook manually
cli-anything-firefly-iii --json webhooks trigger --id 1
インサイトとレポート
# Expense report (by category)
cli-anything-firefly-iii --json insights expense \
  --start 2024-01-01 \
  --end 2024-01-31 \
  --group-by category

# Income report
cli-anything-firefly-iii --json insights income \
  --start 2024-01-01 \
  --end 2024-01-31

# Transfer insights
cli-anything-firefly-iii --json insights transfer \
  --start 2024-01-01 \
  --end 2024-01-31

# Account overview
cli-anything-firefly-iii --json insights overview \
  --start 2024-01-01 \
  --end 2024-01-31
検索
# Search transactions
cli-anything-firefly-iii --json search transactions --query "grocery"
データエクスポート
# Export transactions
cli-anything-firefly-iii --json export transactions \
  --start 2024-01-01 \
  --end 2024-01-31

# Export accounts
cli-anything-firefly-iii --json export accounts

# Export budgets
cli-anything-firefly-iii --json export budgets

# Export categories
cli-anything-firefly-iii --json export categories
システム情報
# System information
cli-anything-firefly-iii --json info about

# Connection status
cli-anything-firefly-iii info status

プリセットフィルタリング

--preset パラメータを使用して、利用可能なコマンドをフィルタリングできます。

# Default preset
cli-anything-firefly-iii --preset default accounts list

# Full preset
cli-anything-firefly-iii --preset full accounts list

# Budget preset
cli-anything-firefly-iii --preset budget budgets list

# Reporting preset
cli-anything-firefly-iii --preset reporting insights expense --start 2024-01-01 --end 2024-01-31

利用可能なプリセット:

  • default: コア機能（accounts、transactions、categories、tags、bills、search）
  • full: すべての機能
  • basic: 基本機能（accounts、transactions、categories、tags、search）
  • budget: 予算関連（accounts、budgets、transactions、summary、insight）
  • reporting: レポート関連（accounts、transactions、categories、insight、summary、search）
  • admin: 管理機能（about、configuration、currencies、users、preferences）
  • automation: 自動化（rules、recurrences、webhooks、transactions）

エージェント向けガイドライン

基本的な使い方
  1. 構造化出力には --json を使用: すべてのコマンドは --json フラグをサポートしており、JSON 形式のデータを返します
  2. 最初に info status を呼び出して接続を確認: 操作を実行する前に Firefly III への接続が正常であることを確認します
  3. プリセットを使用してコマンド数を削減: --preset で不要なコマンドをフィルタリングします
一般的なワークフロー
口座残高の確認
# 1. Check connection
cli-anything-firefly-iii info status

# 2. List asset accounts
cli-anything-firefly-iii --json accounts list --type asset

# 3. View account details (get balance)
cli-anything-firefly-iii --json accounts get --id <account_id>
支出の記録
# 1. Find expense accounts
cli-anything-firefly-iii --json accounts list --type expense

# 2. Create transaction
cli-anything-firefly-iii --json transactions create \
  --description "Lunch" \
  --amount 15.50 \
  --source-account <asset_account_id> \
  --destination-account <expense_account_id> \
  --category "Food"
定期予算の設定
# 1. Create budget
cli-anything-firefly-iii --json budgets create --name "Monthly Groceries"

# 2. Set budget limit
cli-anything-firefly-iii --json budgets limit-create \
  --budget-id <budget_id> \
  --amount 500 \
  --start 2024-01-01 \
  --end 2024-01-31
自動化ルールの作成
# 1. List rule groups
cli-anything-firefly-iii --json rule-groups list

# 2. Create rule
cli-anything-firefly-iii --json rules create \
  --title "Auto-tag groceries" \
  --trigger description_contains \
  --value "grocery" \
  --action set_category \
  --action-value "Food"

# 3. Execute rule to apply to existing transactions
cli-anything-firefly-iii --json rules execute --id <rule_id>
月次財務レポート
# 1. Expense report
cli-anything-firefly-iii --json insights expense \
  --start 2024-01-01 \
  --end 2024-01-31 \
  --group-by category

# 2. Income report
cli-anything-firefly-iii --json insights income \
  --start 2024-01-01 \
  --end 2024-01-31

# 3. Budget summary
cli-anything-firefly-iii --json summary budget-summary \
  --start 2024-01-01 \
  --end 2024-01-31

# 4. Export data
cli-anything-firefly-iii --json export transactions \
  --start 2024-01-01 \
  --end 2024-01-31
エラー処理

一般的なエラーと解決方法:

  1. 接続失敗: FIREFLY_III_BASE_URL が正しいか確認してください
  2. 認証失敗: FIREFLY_III_PAT が有効か確認してください
  3. リソースが見つからない: ID が正しいか確認してください
  4. パラメータエラー: 必須パラメータが指定されているか確認してください
  5. 検証エラー: 有効なパラメータ値については API ドキュメントを確認してください
ベストプラクティス
  1. 認証情報には環境変数を使用する: コマンドラインで PAT を露出させないようにしてください
  2. スクリプト処理には --json を使用する: 出力の解析と処理が容易になります
  3. プリセットで権限を制御する: シナリオに応じて適切なプリセットを選択してください
  4. 変更する前にクエリを実行する: 誤操作を避けてください
  5. クイック検索にはオートコンプリートを使用する: 既存のエンティティを探すのに最適です

トラブルシューティング

接続の問題
Error: Cannot connect to Firefly III instance
  • Firefly III インスタンスが実行中かどうかを確認してください
  • ネットワーク接続を確認してください
  • ベース URL が正しいかどうかを確認してください
認証の問題
Error: Authentication failed: Personal Access Token is invalid
  • PAT が正しいかどうかを確認してください
  • Firefly III の オプション > プロフィール > OAuth で新しい PAT を生成してください
  • PAT が期限切れになっていないことを確認してください
パラメータ検証エラー
Error: Request parameter error: [details]
  • 必須パラメータが指定されているかどうかを確認してください
  • 日付形式 (YYYY-MM-DD) を確認してください
  • 通貨コード (ISO 4217) を確認してください
  • 列挙値が許可された選択肢と一致することを確認してください

MCP バージョンとの比較

機能MCP バージョンCLI-Anything バージョン
プロセスライフサイクル長時間実行単一呼び出し、即時終了
メモリ使用量継続的オンデマンド、実行後に解放
通信Stdio/SSEコマンド引数 + stdout
状態管理ステートフルステートレス
プリセットフィルタリング対応対応
JSON 出力組み込み--json フラグ
完全な API カバレッジ部分的完全な API カバレッジ

API カバレッジ

この CLI は以下の Firefly III API エンドポイントをカバーしています:

  • /api/v1/about - システム情報
  • /api/v1/accounts - 口座管理 (完全な CRUD)
  • /api/v1/transactions - 取引管理 (完全な CRUD)
  • /api/v1/budgets - 予算管理 (完全な CRUD + 限度額)
  • /api/v1/categories - カテゴリ管理 (完全な CRUD)
  • /api/v1/tags - タグ管理 (完全な CRUD)
  • /api/v1/bills - 請求書管理 (完全な CRUD)
  • /api/v1/piggy-banks - 貯金箱管理 (完全な CRUD + イベント)
  • /api/v1/autocomplete/* - すべてのオートコンプリートエンドポイント
  • /api/v1/currencies - 通貨管理 (完全な CRUD)
  • /api/v1/recurrences - 定期取引管理 (完全な CRUD)
  • /api/v1/rules - ルール管理 (完全な CRUD + テスト/実行)
  • /api/v1/rule-groups - ルールグループ管理 (完全な CRUD + 実行)
  • /api/v1/summary/* - サマリーエンドポイント
  • /api/v1/webhooks - Webhook 管理 (完全な CRUD + トリガー)
  • /api/v1/insight/* - インサイトエンドポイント
  • /api/v1/search/* - 検索エンドポイント
  • /api/v1/data/export/* - エクスポートエンドポイント
  • /api/v1/chart/* - チャートエンドポイント
  • /api/v1/configuration - 設定
  • /api/v1/preferences - ユーザー設定
  • /api/v1/available_budgets - 利用可能な予算
  • /api/v1/object-groups - オブジェクトグループ
  • /api/v1/links - 取引リンク
  • /api/v1/attachments - 添付ファイル
  • /api/v1/currency_exchange_rates - 為替レート
  • /api/v1/data/bulk - 一括操作
  • /api/v1/user-groups - ユーザーグループ (読み取り専用)
  • /api/v1/users - ユーザー管理 (管理者)

ライセンス

MIT License

コメント

Markdown 対応