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

Tool Schema Changelog

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

Loading tool schema changelog…

    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