内容
# 火蝶 III MCP 服务器（Go语言）
一款轻量级的火蝶 III 模型上下文协议（MCP）服务器，使用Go语言编写。该服务器允许AI助手与您的火蝶 III 实例交互，以管理账户、交易和类别。
## 功能
- **创建账户** - 创建银行账户、费用账户、收入账户等
- **创建交易** - 记录取款、存款和转账
- **创建类别** - 使用类别组织交易
- **列出资源** - 查看现有的账户、类别和交易
## 先决条件
- Go 1.22 或更高版本
- 运行中的 [火蝶 III](https://www.firefly-iii.org/) 实例
- 火蝶 III 个人访问令牌（PAT）
## 安装
### 从源代码编译
```bash
git clone https://github.com/codemi/firefly-iii-mcp-go.git
cd firefly-iii-mcp-go
make build
```
### 下载二进制文件
从 [Releases](https://github.com/codemi/firefly-iii-mcp-go/releases) 页面下载适用于您平台的预编译二进制文件。
## 获取个人访问令牌
1. 登录到您的火蝶 III 实例
2. 导航到 **选项 > 配置文件 > OAuth**
3. 在“个人访问令牌”下，点击 **创建新令牌**
4. 为其命名（例如，“MCP 服务器”）
5. 立即复制生成的令牌（您将不会再次看到它）
## 使用
### 命令行
```bash
# 使用 .env 文件（推荐）
cp .env.example .env
# 使用您的值编辑 .env
./bin/firefly-mcp
# 使用命令行标志
./bin/firefly-mcp --baseUrl https://firefly.example.com --pat YOUR_TOKEN
# 使用环境变量
export FIREFLY_III_BASE_URL="https://firefly.example.com"
export FIREFLY_III_PAT="YOUR_TOKEN"
./bin/firefly-mcp
```
### 服务器模式
服务器支持两种模式：
#### 标准输入/输出模式（默认）
适用于通过标准输入/输出通信的CLI工具，如Claude Desktop。
```bash
./bin/firefly-mcp --mode stdio
```
#### SSE模式
带有服务器端事件的HTTP服务器，适用于Web应用程序。
```bash
./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配合使用
将以下内容添加到您的Claude Desktop配置中（Linux上为`~/.config/claude/claude_desktop_config.json`，macOS上为`~/Library/Application Support/Claude/claude_desktop_config.json`）：
```json
{
"mcpServers": {
"firefly-iii": {
"command": "/path/to/firefly-mcp",
"args": [
"--baseUrl", "https://firefly.example.com",
"--pat", "YOUR_TOKEN"
]
}
}
}
```
或使用环境变量：
```json
{
"mcpServers": {
"firefly-iii": {
"command": "/path/to/firefly-mcp",
"env": {
"FIREFLY_III_BASE_URL": "https://firefly.example.com",
"FIREFLY_III_PAT": "YOUR_TOKEN"
}
}
}
}
```
## 可用工具
### `store_account`
在火蝶 III中创建一个新账户。
**必填参数：**
- `name` - 账户名称（例如，“我的储蓄账户”）
- `type` - 账户类型：`asset`、`expense`、`revenue`、`cash`、`liability`
**可选参数：**
- `iban` - IBAN
- `bic` - BIC/SWIFT代码
- `account_number` - 账户号码
- `opening_balance` - 开户余额（例如，“1000.00”）
- `opening_balance_date` - 日期，格式为YYYY-MM-DD
- `currency_code` - 货币（例如，“EUR”，“USD”）
- `account_role` - 资产账户角色
- `notes` - 其他备注
### `store_transaction`
在火蝶 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`
在火蝶 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`
## 开发
### 编译
```bash
make build
```
### 为所有平台编译
```bash
make build-all
```
### 运行测试
```bash
make test
```
### 清理
```bash
make clean
```
## 许可证
MIT 许可证 - 参见 [LICENSE](LICENSE) 了解详情。
## 致谢
灵感来自 [firefly-iii-mcp](https://github.com/etnperlong/firefly-iii-mcp) TypeScript 实现。
