Firefly III MCP服务器
一个模型上下文协议（MCP）服务器，为人工智能助理提供安全、全面的访问您自托管的Firefly III个人财务经理的权限。
目的
此MCP服务器使AI助手（如Claude）能够通过以下方式帮助您管理个人财务：
- 记录交易（支出、收入、转账）
- 管理账户、预算、类别和标签
- 分析支出模式和财务数据
- 整理和分类您的财务记录
特性
100%完成API覆盖范围-236个工具
此MCP服务器提供 100%完全覆盖 Firefly III REST API的所有229个基本方法-所有28个API类。
系统与健康（3个工具）：
health_check-验证API连接和身份验证get_system_info-获取Firefly III版本、用户信息和系统详细信息get_cron_status-获取cron作业状态和配置
账户管理（9个工具）：
list_accounts-列出所有具有可选类型和名称筛选的帐户get_account_details-获取特定帐户的详细信息create_account-创建新账户（资产、支出、收入等）update_account-更新帐户名、活动状态或备注delete_account-删除帐户（需要确认）list_account_transactions-列出特定账户的所有交易list_attachments_by_account-列出帐户的所有附件list_piggy_banks_by_account-列出与账户关联的存钱罐
交易操作（14种工具）：
list_transactions-列出具有日期范围和类型筛选的交易记录get_transaction_details-获取交易的详细信息create_withdrawal-创建具有完整元数据的支出交易记录create_deposit-创建具有完整元数据的收入交易create_transfer-在资产账户之间创建转账update_transaction-更新现有交易详细信息delete_transaction-删除交易（需要确认）list_transactions_for_period-列出特定时间段内的交易list_transactions_without_budget-查找未编入预算的交易list_transactions_without_category-查找未分类的交易delete_transaction_journal-按日记账ID删除交易get_transaction_by_journal-按日记账ID获取交易list_transaction_events-列出事务的审核日志事件list_transaction_links_by_journal-列出交易日志的链接
预算管理（15种工具）：
list_budgets-列出所有预算get_budget_details-获取详细的预算信息create_budget-创建新预算update_budget-更新预算详细信息delete_budget-删除预算（需要确认）list_budget_limits-列出预算的支出限额get_budget_spending-获取一段时间内预算的支出数据list_transactions_by_budget-列出预算中的所有交易记录get_budget_limit_details-获取特定预算限额的详细信息list_all_budget_limits-列出所有预算的所有预算限额create_budget_limit-创建新的预算限额update_budget_limit-更新现有预算限额delete_budget_limit-删除预算限制list_attachments_by_budget-列出预算的所有附件list_transactions_by_budget_limit-列出特定预算限额的交易记录
类别管理（7个工具）：
list_categories-列出所有类别get_category_details-获取详细的类别信息create_category-创建新类别update_category-更新类别详细信息delete_category-删除类别（需要确认）list_transactions_by_category-列出一个类别中的所有交易list_attachments_by_category-列出某一类别的所有附件
标签管理（6个工具）：
list_tags-列出所有标签get_tag_details-获取详细的标签信息create_tag-创建一个带有可选日期和描述的新标签update_tag-更新标签详细信息delete_tag-删除标签（需要确认）list_transactions_by_tag-列出具有特定标签的所有交易
账单（6个工具）：
list_bills-列出所有具有可选活动/非活动筛选的账单get_bill_details-获取账单的详细信息create_bill-创建新账单update_bill-更新账单详细信息delete_bill-删除账单（需要确认）list_bill_transactions-列出与账单关联的所有交易list_attachments_by_bill-列出账单的所有附件list_rules_by_bill-列出引用账单的所有规则
小猪银行（7个工具）：
list_piggy_banks-列出所有存钱罐get_piggy_bank_details-获取存钱罐的详细信息create_piggy_bank-创建一个新的存钱罐update_piggy_bank-更新存钱罐详细信息delete_piggy_bank-删除存钱罐（需要确认）list_piggy_bank_events-列出存钱罐的所有事件list_attachments_by_piggy_bank-列出存钱罐的所有附件
自动补全（15个工具）：
autocomplete_accounts-获取帐户名建议autocomplete_categories-获取类别名称建议autocomplete_tags-获取标签名称建议autocomplete_budgets-获取预算名称建议autocomplete_currencies-获取货币建议autocomplete_currency_codes-获取货币代码建议autocomplete_object_groups-获取对象组建议autocomplete_piggy_banks_with_balance-用余额获取存钱罐建议autocomplete_recurring_transactions-获取定期交易建议autocomplete_rule_groups-获取规则组建议autocomplete_rules-获取规则建议autocomplete_subscriptions-获取订阅（账单）建议autocomplete_transaction_types-获取交易类型建议autocomplete_transactions-获取交易建议autocomplete_transaction_ids-获取交易ID建议
货币（17种工具）：
list_currencies-列出所有货币（启用和禁用）get_currency_details-获取货币的详细信息enable_currency-启用货币以供使用disable_currency-禁用货币set_default_currency-设置系统的默认货币delete_currency-删除货币get_primary_currency-获取主要（默认）货币set_primary_currency-将货币设置为主要货币create_currency-创建新货币update_currency-更新货币详细信息list_accounts_by_currency-列出使用货币的帐户list_available_budgets_by_currency-以货币列出可用预算list_bills_by_currency-以货币列出账单list_budget_limits_by_currency-以货币列出预算限额list_recurrences_by_currency-以货币列出经常性交易list_rules_by_currency-列出引用货币的规则list_transactions_by_currency-以货币列出交易记录
搜索（3个工具）：
search_all-搜索所有Firefly III实体（账户、交易等）search_accounts_specific-使用字段筛选专门搜索帐户search_transactions_specific-专门搜索交易
见解（4种工具）：
spending_summary-获取日期范围的支出摘要income_summary-获取日期范围的收入汇总net_flow_summary-获取一段时间的净现金流（收入-支出）insight_transfers_overview-获取账户间转账的一般概述
规则和规则组（13个工具）：
list_rule_groups-列出所有规则组get_rule_group_details-获取规则组的详细信息create_rule_group-创建新规则组update_rule_group-更新规则组详细信息delete_rule_group-删除规则组（需要确认）list_rules-按规则组列出所有具有可选筛选功能的规则get_rule_details-获取规则的详细信息create_rule-使用触发器和操作创建新规则update_rule-更新规则详细信息、触发器和操作delete_rule-删除规则（需要确认）test_rule-根据现有交易测试规则trigger_rule-手动触发规则运行fire_rule_group-在现有事务上触发规则组test_rule_group-在不应用更改的情况下测试规则组
重复（8个工具）：
list_recurrences-列出所有经常性交易get_recurrence_details-获取重复的详细信息create_recurrence-创建新的定期交易update_recurrence-更新重复详细信息delete_recurrence-删除重复（需要确认）list_recurrence_transactions-列出重复创建的实际交易trigger_recurrence_now-手动触发重复以立即创建事务
Webhooks（14个工具）：
list_webhooks-列出所有Webhookget_webhook_details-获取webhook的详细信息create_webhook-创建新的webhookupdate_webhook-更新webhook详细信息delete_webhook-删除webhook（需要确认）trigger_webhook_test-触发测试webhook调用list_webhook_messages-列出webhook发送的所有消息delete_webhook_message-删除webhook消息delete_webhook_message_attempt-删除webhook消息尝试get_webhook_message-获取webhook消息的详细信息get_webhook_message_attempt-获取webhook消息尝试的详细信息list_webhook_message_attempts-列出webhook消息的所有尝试trigger_transaction_webhook-手动触发特定事务的webhook
附件（7个工具）：
list_attachments-列出所有附件get_attachment_details-获取附件的详细信息delete_attachment-删除附件（需要确认）download_attachment-下载附件文件内容create_attachment-创建新附件（不上传文件）update_attachment-更新附件元数据upload_attachment_file-将文件内容上传到附件（base64）
可用预算（6个工具）：
list_available_budgets-列出所有可用的预算金额get_available_budget_details-获取可用预算的详细信息create_available_budget-创建新的可用预算金额update_available_budget-更新可用预算详细信息delete_available_budget-删除可用预算（需要确认）
链接（11个工具）：
list_transaction_links-列出所有交易链接get_transaction_link_details-获取交易链接的详细信息delete_transaction_link-删除交易链接（需要确认）list_transaction_link_types-列出所有交易链接类型get_transaction_link_type-获取交易链接类型的详细信息create_transaction_link_type-创建新的交易链接类型update_transaction_link_type-更新交易链接类型delete_transaction_link_type-删除交易链接类型list_transactions_by_link_type-使用链接类型列出交易create_transaction_link-在两个交易之间创建链接update_transaction_link_notes-更新交易链接的注释
首选项和配置（7个工具）：
list_preferences-列出所有用户首选项get_preference-获取特定的偏好值get_configuration-获取Firefly III系统配置create_preference-创建新的用户首选项update_preference-更新现有用户首选项get_single_configuration_value-按名称获取单个配置值set_configuration_value-设置配置值
数据导出（2个工具）：
export_accounts-以CSV格式导出帐户数据export_transactions-以CSV格式导出交易数据
通用逃生舱口（1个工具）：
firefly_raw_request-对不受支持的终结点发出任意API请求
图表（4个工具）：
get_chart_account_overview-账户余额概览图表数据get_chart_balance-账户余额随时间变化的图表数据get_chart_budget_overview-预算支出概览图表数据get_chart_category_overview-类别支出概览图表数据
货币汇率（12种工具）：
list_currency_exchange_rates-列出所有汇率get_currency_exchange_rate-获取具体汇率详细信息get_exchange_rate_on_date-获取当日货币对的汇率list_exchange_rates_for_pair-列出日期范围内货币对的汇率create_exchange_rate-创建新汇率create_exchange_rate_by_date-为特定日期创建费率create_exchange_rate_by_pair-按货币对创建汇率update_exchange_rate-更新现有汇率update_exchange_rate_by_date-特定日期的更新率delete_exchange_rate-删除汇率delete_exchange_rate_on_date-删除特定日期的费率delete_exchange_rates_for_pair-删除范围内配对的所有费率
数据操作（10个工具）：
bulk_update_transactions-批量更新多个交易export_bills-将账单导出到CSVexport_budgets-将预算导出到CSVexport_categories-将类别导出到CSVexport_piggy_banks-将存钱罐导出到CSVexport_recurring_transactions-将经常性交易导出到CSVexport_rules-将规则导出到CSVexport_tags-将标签导出到CSVdestroy_data-软删除特定数据类型purge_data-永久清除所有数据（危险）
扩展洞察（21个工具）：
insight_expense_asset-按资产账户划分的支出洞察insight_expense_bill-按账单列出的支出洞察insight_expense_budget-按预算列出的支出洞察insight_expense_category-按类别划分的支出洞察insight_expense_expense_account-按支出账户列出的支出洞察insight_expense_no_bill-无账单费用insight_expense_no_budget-无预算费用insight_expense_no_category-无类别费用insight_expense_no_tag-无标签费用insight_expense_tag-按标签列出的支出洞察insight_expense_total-总费用洞察insight_income_asset-按资产账户划分的收入洞察insight_income_category-按类别划分的收入洞察insight_income_no_category-无类别收入insight_income_no_tag-无标签收入insight_income_revenue-按收入账户划分的收入洞察insight_income_tag-按标签分类的收入洞察insight_income_total-总收入洞察insight_transfer_category-按类别转移见解insight_transfer_no_category-无类别转移insight_transfer_no_tag-无标签传输insight_transfer_tag-按标签转移见解insight_transfer_total-总转移见解
对象组（6个工具）：
list_object_groups-列出所有对象组get_object_group-获取对象组详细信息update_object_group-更新对象组delete_object_group-删除对象组list_bills_by_object_group-按组列出账单list_piggy_banks_by_object_group-按组列出存钱罐
摘要（1个工具）：
get_basic_summary-获取日期范围的仪表板摘要
用户组（3个工具）：
list_user_groups-列出所有用户组get_user_group-获取用户组详细信息update_user_group-更新用户组
用户（5个工具）：
list_users-列出所有用户（管理员）get_user-获取用户详细信息create_user-创建新用户（管理员）update_user-更新用户详细信息（管理员）delete_user-删除用户（admin）
先决条件
- Python 3.8或更高版本
- 克劳德桌面版
- 访问~/.config/mcp-secrets.json获取凭据
- 正在运行的Firefly III实例（自托管或云）
- Firefly III实例中的个人访问令牌
安装
有关完整的分步安装说明，请参阅下面的第2节。
使用示例
在Claude Desktop中，您可以问：
账户管理
- “列出我的所有资产账户”
- “显示我的支票账户的详细信息”
- “创建一个名为“紧急基金”的新储蓄账户”
- “账户ID 1的余额是多少？”
- “显示我支票账户的所有交易记录”
事务管理
- “显示本月的所有交易记录”
- “从我的支票账户中记录50美元的杂货费”
- “在我的支票账户中存入2000美元的工资”
- “将500美元从支票转入储蓄”
- “交易ID 123的详细信息是什么？”
- “更新交易456，将金额更改为75美元”
- “显示所有未分类的交易”
预算和类别
- “列出我的所有预算”
- “创建一个名为‘杂货’的新预算，每月500美元”
- “告诉我这个月我的杂货预算花了多少钱”
- “显示所有类别”
- “为‘运输’创建一个类别”
- “列出杂货类别中的所有交易”
标签
- “列出所有标签”
- “为今天的‘出差’创建一个标签”
- “显示所有标记为“度假”的交易”
账单和经常性交易
- “列出我的所有账单”
- “为Netflix创建账单，每月15.99美元”
- “显示我的电费账单的所有交易”
- “为我的租金创建定期交易”
- “列出所有活动的重复交易”
小猪银行
- “列出我所有的存钱罐”
- “为‘度假基金’创建一个存钱罐，目标是5000美元”
- “给我看看我的应急基金存钱罐的历史”
规则与自动化
- “列出我的所有交易规则”
- “制定一条规则，将优步的费用自动归类为交通费用”
- “测试规则ID 5，看看它会做什么”
- “手动触发规则‘对亚马逊进行分类’”
洞察与分析
- “我上个月的总支出是多少？”
- “给我看看我今年的收入”
- “计算我第一季度的净现金流”
- “搜索所有提及‘咖啡’的交易”
高级操作
- “列出所有webhook配置”
- “将2024年的所有交易导出为CSV”
- “显示所有可用货币”
- “列出我的所有交易链接”
图表和仪表板
- “获取我过去3个月支票账户余额的图表数据”
- “显示第一季度的预算支出图表”
- “生成今年的类别概览图”
- “获取我12月份的基本财务摘要”
汇率
- “列出所有货币汇率”
- “2024年12月1日欧元兑美元汇率是多少？”
- “创建汇率：美元兑墨西哥比索=18.5”
- “将汇率42更新为19.2”
延伸洞察
- “显示我支票账户的支出明细”
- “没有分配任何预算，我的开支是多少？”
- “给我工资类别的收入见解”
- “显示Business标签的转账见解”
对象组和组织
- “列出所有对象组”
- “显示对象组3中的所有账单”
- “为订阅服务创建对象组”
多用户和管理员
- “列出所有用户”（仅限管理员）
- “使用电子邮件创建新用户john@example.com“（仅限管理员）
- “列出所有用户组”
批量操作
- “将我的所有预算导出到CSV”
- “将所有规则导出到备份”
- “批量更新这10笔交易…”
建筑
Claude Desktop → Firefly III MCP Server (Python/venv) → Firefly III API
↓
~/.config/mcp-secrets.json发展
局部测试
# Ensure secrets are configured in ~/.config/mcp-secrets.json
# Activate virtual environment
source ~/.local/share/mcp-servers/mcp-firefly/venv/bin/activate
# Run directly
python firefly_server.py
# Test MCP protocol
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | python firefly_server.py
# Deactivate venv
deactivate添加新工具
- 将该功能添加到
firefly_server.py - 用…装饰
@mcp.tool() - 如果需要新的依赖关系，请添加到requirements.txt并重新安装：
source venv/bin/activate
pip install -r requirements.txt
deactivate- 重新启动克劳德桌面
故障排除
工具未出现
- 检查克劳德桌面日志：
~/.config/Claude/logs/mcp.log - 验证Claude配置中的服务器路径是否正确
- 确保venv已正确配置所有依赖项
- 检查服务器运行是否无错误：
source venv/bin/activate && python firefly_server.py - 重新启动克劳德桌面
身份验证错误
- 验证~/.config/mcp-secrets.json是否存在并且格式正确
- 检查机密文件的权限（应为600）
- 确保“firefly”密钥存在于secrets文件中
- 验证base_url和令牌值是否正确
- 测试API访问：
curl -H "Authorization: Bearer YOUR_TOKEN" https://your-firefly.com/api/v1/about
API错误
- 检查您的Firefly III实例是否正在运行且可访问
- 验证secrets文件中的base_url是否正确（应以/api结尾或让服务器附加它）
- 确保您的个人访问令牌尚未过期
- 检查Firefly III日志是否有任何服务器端错误
安全考虑
- 所有秘密都存储在~/.config/mcp-secrets.json中，具有600个权限
- 永远不要在代码中硬编码凭据
- 机密文件永远不应该提交给git
- 敏感数据从未记录到stderr
- 服务器以用户权限运行（不需要root）
- 破坏性操作（删除）需要明确确认
- 所有API通信都使用HTTPS（验证您的Firefly III实例是否使用SSL）
API 文档
- Firefly III API文档：https://api-docs.firefly-iii.org/
- Python客户端：https://github.com/ms32035/firefly-iii-client
- 萤火虫III GitHub：https://github.com/firefly-iii/firefly-iii
许可证
MIT许可证