AI导哈

Firefly III MCP服务端

一个轻量级的Firefly III模型上下文协议(MCP)服务端，用于AI助手管理账户、交易和类别。

  • by BauhouseConsorxium
  • Go
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 BauhouseConsorxium/FireflyMCP

使用说明

Firefly III MCP服务器（Go）

一个轻量级的模型上下文协议（MCP）服务器 萤火虫III用Go写的。此服务器允许AI助手与您的Firefly III实例交互，以管理帐户、交易和类别。

特性

  • 创建帐户 -创建银行账户、支出账户、收入账户等。
  • 创建交易 -记录提款、存款和转账
  • 创建类别 -按类别组织您的交易
  • 列出资源 -查看现有帐户、类别和交易

先决条件

  • 转到1.22或更高版本
  • 跑步 萤火虫III 例子
  • Firefly III个人访问令牌（PAT）

安装

来源

git clone https://github.com/codemi/firefly-iii-mcp-go.git
cd firefly-iii-mcp-go
make build

下载二进制文件

从以下网址下载适用于您平台的预构建二进制文件 发布 页面。

获取个人访问令牌

  1. 登录您的Firefly III实例
  2. 导航到 选项>配置文件>OAuth
  3. 在“个人访问令牌”下，单击 创建新令牌
  4. 为其命名（例如，“MCP服务器”）
  5. 立即复制生成的令牌（您将不会再看到它）

用法

命令行

# Using .env file (recommended)
cp .env.example .env
# Edit .env with your values
./bin/firefly-mcp

# Using command-line flags
./bin/firefly-mcp --baseUrl https://firefly.example.com --pat YOUR_TOKEN

# Using environment variables
export FIREFLY_III_BASE_URL="https://firefly.example.com"
export FIREFLY_III_PAT="YOUR_TOKEN"
./bin/firefly-mcp

服务器模式

服务器支持两种模式：

标准模式（默认）

适用于通过标准输入/输出进行通信的CLI工具，如Claude Desktop。

./bin/firefly-mcp --mode stdio

SSE模式

带有web应用程序服务器发送事件的HTTP服务器。

./bin/firefly-mcp --mode sse --port 3000

终点：

  • GET /sse -建立SSE连接
  • POST /message -向服务器发送消息

配置

配置按以下优先级顺序加载：

  1. 命令行标志（最高优先级）
  2. 环境变量
  3. .env 文件（最低优先级）

可用选项：

标志 环境变量 默认值 描述
--baseUrl FIREFLY_III_BASE_URL - 萤火虫III实例URL
--pat FIREFLY_III_PAT - 个人访问令牌
--mode FIREFLY_III_MODE stdio 服务器模式： stdio 或 sse
--port FIREFLY_III_PORT 3000 SSE模式端口

使用克劳德桌面

添加到您的Claude Desktop配置(~/.config/claude/claude_desktop_config.json 在Linux或 ~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

{
  "mcpServers": {
    "firefly-iii": {
      "command": "/path/to/firefly-mcp",
      "args": [
        "--baseUrl", "https://firefly.example.com",
        "--pat", "YOUR_TOKEN"
      ]
    }
  }
}

或者使用环境变量：

{
  "mcpServers": {
    "firefly-iii": {
      "command": "/path/to/firefly-mcp",
      "env": {
        "FIREFLY_III_BASE_URL": "https://firefly.example.com",
        "FIREFLY_III_PAT": "YOUR_TOKEN"
      }
    }
  }
}

可用工具

store_account

在Firefly III中创建新帐户。

所需参数：

  • name -账户名称（例如“我的支票账户”）
  • type -账户类型： asset, expense, revenue, cash, liability

可选参数：

  • iban -伊班
  • bic -BIC/SWIFT代码
  • account_number -账号
  • opening_balance -期初余额（例如“1000.00”）
  • opening_balance_date -YYYY-MM-DD格式的日期
  • currency_code -货币（例如“欧元”、“美元”）
  • account_role -资产账户的角色
  • notes -附加说明

store_transaction

在Firefly III中创建新交易。

所需参数：

  • type -交易类型： withdrawal, deposit, transfer
  • description -交易描述
  • amount -金额（例如“25.50”）
  • date -YYYY-MM-DD格式的日期

可选参数：

  • source_name -源账户名称（提款/转账时需要）
  • destination_name -目的地账户名称（存款/转账所需）
  • category_name -交易的类别
  • currency_code -货币代码
  • notes -附加说明
  • tags -以逗号分隔的标签列表
  • apply_rules -是否应用规则（默认值：true）

store_category

在Firefly III中创建一个新类别。

所需参数：

  • name -类别名称（例如“杂货”）

可选参数：

  • notes -附加说明

list_accounts

列出所有帐户，可选择按类型筛选。

可选参数：

  • type -按类型筛选： all, asset, expense, revenue, cash, liability

list_categories

列出所有类别。

list_transactions

列出日期范围内的交易。

可选参数：

  • start -YYYY-MM-DD格式的开始日期
  • end -YYYY-MM-DD格式的结束日期
  • type -按类型筛选： all, withdrawal, deposit, transfer

发展

构建

make build

为所有平台构建

make build-all

运行测试

make test

清洁

make clean

许可证

MIT许可证-请参阅 许可证 了解详情。

致谢

灵感来自 萤火虫iii mcp TypeScript实现。

相关 MCP