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 输出与命令预设，适用于脚本和 Agent 工作流。

主要功能

  1. 01管理账户和交易
  2. 02管理预算、账单与类别
  3. 03处理规则、定期交易和 Webhook
  4. 04搜索、导出并查看报告
  5. 05通过预设筛选命令
  6. 06返回结构化 JSON

适用场景

  1. 01记录支出并查看账户余额
  2. 02生成收入和支出报告
  3. 03使用规则或定期交易实现自动化
  4. 04通过 JSON 输出编写 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 模式转换为无状态命令行模式，以避免 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）

Agent 指南

基本用法
  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 实例是否正在运行
  • 检查网络连接
  • 检查 base URL 是否正确
认证问题
Error: Authentication failed: Personal Access Token is invalid
  • 检查 PAT 是否正确
  • 在 Firefly III 的 Options > Profile > 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