Skip to main content
Glama
Firefly III MCP Server

Firefly III MCP Server

by edmondxie779

Firefly III MCP Server (firefly-iii-mcp)

适用于 Firefly III 个人财务管理系统的标准 Model Context Protocol (MCP) 服务端(TypeScript / Node.js)。支持在 Claude Desktop、Cursor、Antigravity、Windsurf 等任意兼容 MCP 的客户端中通过自然语言查账、管账户、记账与搜索流水。

功能特性(Tools)

系统与财务概览

Tool

说明

get_system_info

检查与 Firefly III 实例的连通性,返回系统版本、API 版本及当前登录用户信息

get_financial_summary

获取指定日期范围内的财务概览(净资产、收支汇总、待付账单、可支配余额等)

账户管理(Accounts)

Tool

说明

list_accounts

查询账户列表及余额(支持按 asset / expense / revenue / liability / cash 过滤及指定历史日期余额)

get_account

根据账户 ID 获取单个账户详情与余额

search_accounts

按名称、卡号/账号、IBAN 或 ID 搜索账户

create_account

创建新账户(自动为资产账户补充默认 defaultAsset 角色,并对负债/信用卡必填项做前置校验)

update_account

更新账户信息(支持部分字段更新,未传 name 时自动保留原账户名)

delete_account

根据 ID 删除账户

list_account_transactions

查询指定账户名下的交易流水(支持日期范围与交易类型筛选)

交易记录(Transactions)

Tool

说明

list_transactions

按日期范围(start / end)和类型(withdrawal / deposit / transfer)分页查询交易记录

get_transaction

获取单笔(或拆分交易组)的完整明细

search_transactions

使用 Firefly III 高级搜索语法检索交易(例如 type:withdrawal category_is:"餐饮" amount_more:50)

create_transaction

创建支出(withdrawal)、收入(deposit)或转账(transfer),支持单笔及多笔拆分记账(Split Transactions)、多币种、分类、预算与标签

update_transaction

修改已有交易记录或拆分明细

delete_transaction

删除指定交易记录


Related MCP server: Firefly III MCP Server

前置准备:获取 Firefly III Personal Access Token

  1. 登录你的 Firefly III 网页端。

  2. 进入 Options(选项) -> Profile(个人资料) -> OAuth 页面。

  3. 在 Personal Access Tokens 区域点击 Create New Token,输入名称(例如 MCP Server)并复制生成的长 Token。


本地构建与运行

环境要求:Node.js >= 20

# 安装依赖
npm install

# 编译 TypeScript 到 dist/
npm run build

# 运行单元测试与 MCP 协议集成测试
npm test

在 MCP 客户端中配置

方式一:直接使用本地构建产物

{
  "mcpServers": {
    "firefly-iii": {
      "command": "node",
      "args": ["/path/to/firefly-iii-mcp/dist/index.js"],
      "env": {
        "FIREFLY_III_URL": "https://your-firefly-instance.example.com",
        "FIREFLY_III_PAT": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9..."
      }
    }
  }
}

方式二:发布到 npm 后通过 npx 启动

{
  "mcpServers": {
    "firefly-iii": {
      "command": "npx",
      "args": ["-y", "firefly-iii-mcp"],
      "env": {
        "FIREFLY_III_URL": "https://your-firefly-instance.example.com",
        "FIREFLY_III_PAT": "your_personal_access_token"
      }
    }
  }
}

环境变量说明

变量名

必填

说明

FIREFLY_III_URL

是

Firefly III 实例地址(如 http://localhost:8080 或 https://money.example.com,兼容自动去除末尾 /api/v1)。亦支持别名 FIREFLY_BASE_URL

FIREFLY_III_PAT

是

Firefly III OAuth Personal Access Token。亦支持别名 FIREFLY_III_TOKEN

FIREFLY_III_TIMEOUT_MS

否

请求超时时间(毫秒),默认 30000

许可协议

MIT

Available Tools

15 tools
create_accountCreate AccountA

Create a new account in Firefly III. For 'asset' accounts, 'account_role' defaults to 'defaultAsset' (if 'ccAsset', also pass 'credit_card_type' and 'monthly_payment_date'). For 'liability' accounts, 'liability_type' ('loan', 'debt', or 'mortgage') is required.

Inputs: name (required), type (required), bic, iban, +15 more.

create_transactionCreate TransactionA

Record a new transaction (or multi-split transaction group) in Firefly III.

  • For an expense ('withdrawal'): specify your asset account via 'source_id' or 'source_name', and the merchant via 'destination_name' (or 'destination_id').

  • For income ('deposit'): specify the payer/revenue source via 'source_name' (or 'source_id'), and your asset account via 'destination_id' or 'destination_name'.

  • For a transfer ('transfer'): specify both 'source_id'/'source_name' and 'destination_id'/'destination_name' pointing to two of your own asset/liability accounts.

Inputs: transactions (required), apply_rules, group_title, fire_webhooks, +1 more.

delete_accountDelete AccountA
DestructiveIdempotent

Permanently delete a Firefly III account by ID. Warning: deleting an account may also affect or delete transactions exclusively linked to it.

Inputs: id (required).

delete_transactionDelete TransactionA
DestructiveIdempotent

Permanently delete a Firefly III transaction group (and all of its splits) by transaction ID.

Inputs: id (required).

get_accountGet Account DetailsA
Read-onlyIdempotent

Get detailed attributes and current balance for a single Firefly III account by its ID.

Inputs: id (required), date.

get_financial_summaryGet Financial SummaryA
Read-onlyIdempotent

Retrieve Firefly III's basic financial summary (net worth, balance, earned, spent, bills, left to spend) for a given date range.

Inputs: end (required), start (required), currency_code.

get_system_infoGet Firefly III System & User InfoA
Read-onlyIdempotent

Verify connectivity to Firefly III and retrieve instance version, API version, and authenticated user profile.

Inputs: no named parameters.

get_transactionGet Transaction DetailsA
Read-onlyIdempotent

Retrieve a single Firefly III transaction group and all of its journal splits by transaction ID.

Inputs: id (required).

list_accountsList AccountsA
Read-onlyIdempotent

List Firefly III accounts and their balances. Filter by account type (e.g. 'asset' for bank/checking/savings/credit cards, 'expense' for merchants, 'revenue' for income sources, 'liability' for loans/debts).

Inputs: date, page, type, limit.

list_account_transactionsList Account TransactionsB
Read-onlyIdempotent

List transactions associated with a specific Firefly III account ID, optionally filtered by date range and transaction type.

Inputs: account_id (required), end, page, type, +2 more.

list_transactionsList TransactionsB
Read-onlyIdempotent

List Firefly III transactions with optional date range ('start', 'end' in YYYY-MM-DD) and transaction type filter ('withdrawal', 'deposit', 'transfer', or 'all').

Inputs: end, page, type, limit, +1 more.

search_accountsSearch AccountsA
Read-onlyIdempotent

Search Firefly III accounts by name, account number, IBAN, or ID.

Inputs: query (required), page, type, field, +1 more.

search_transactionsSearch TransactionsA
Read-onlyIdempotent

Search Firefly III transactions using Firefly III's search query syntax. Multiple terms are combined with AND. Wrap multi-word values in quotes. Useful operators: type:withdrawal|deposit|transfer, date_after:YYYY-MM-DD, date_before:YYYY-MM-DD, date_is:YYYY-MM-DD, amount_is:N, amount_more:N, amount_less:N, source_is:"Checking", destination_is:"Amazon", category_is:"Food", budget_is:"Groceries", tag_is:"trip", description_contains:"coffee", notes_contain:"reimburse", has_any_category:false, reconciled:true. Prefix any filter with '-' to negate.

Inputs: query (required), page, limit.

update_accountUpdate AccountB
Idempotent

Update an existing Firefly III account by ID. Only fields you pass will be modified (if 'name' is omitted, the existing account name is preserved automatically).

Inputs: id (required), bic, iban, name, +14 more.

update_transactionUpdate TransactionA
Idempotent

Update an existing Firefly III transaction group by ID. When updating a multi-split transaction, pass 'transaction_journal_id' inside each split (retrieve them first with 'get_transaction').

Inputs: id (required), apply_rules, group_title, transactions, +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 15 tools

    Disambiguation4/5

    Tools are mostly distinct: account CRUD, transaction CRUD, search, and summary have clear purposes. A few pairs, such as list_accounts vs. search_accounts and list_transactions vs. search_transactions, could be confused, but descriptions clarify the differences.

    Naming Consistency5/5

    All tool names use a consistent snake_case verb_noun pattern such as get_account, create_transaction, and delete_account. The naming is predictable and easy to scan.

    Tool Count5/5

    With 15 tools, the server is well-scoped for account and transaction management. Each tool appears to earn its place without excessive surface area.

    Completeness4/5

    Account and transaction CRUD, search, listing, and financial summary are well covered. Broader Firefly III entities like budgets, categories, tags, and bills are not managed, but core workflows are still supported.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • -
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables AI tools to interact with Firefly III personal finance management instances through a cloud-deployed MCP server. Supports financial operations like account management, transactions, budgeting, and reporting with configurable tool presets.
      19 npm
      -
    • A
      license
      A
      quality
      D
      maintenance
      Integrates with Firefly III personal finance software to enable natural language management of transactions, accounts, budgets, and categories. Supports recording expenses, checking balances, and organizing financial data through conversational AI.
      23
      7 npm
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables querying personal finance data including accounts, transactions, spending, holdings, net worth, and budgets from your self-hosted OpenCoffer instance. Supports natural language queries through any MCP-compatible client.
      19
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Connects any MCP-compatible AI assistant to your Firefly III personal finance instance, enabling natural language queries about your finances.
      MIT