Firefly MCP (Bauhouse Consorxium)

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 文件（最低优先级）

可用选项：

使用克劳德桌面

添加到您的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实现。