Content
# Firefly III MCP Server (Go)
A lightweight Model Context Protocol (MCP) server for [Firefly III](https://www.firefly-iii.org/), written in Go. This server allows AI assistants to interact with your Firefly III instance to manage accounts, transactions, and categories.
## Features
- **Create Accounts** - Create bank accounts, expense accounts, revenue accounts, etc.
- **Create Transactions** - Record withdrawals, deposits, and transfers
- **Create Categories** - Organize your transactions with categories
- **List Resources** - View existing accounts, categories, and transactions
## Prerequisites
- Go 1.22 or later
- A running [Firefly III](https://www.firefly-iii.org/) instance
- A Firefly III Personal Access Token (PAT)
## Installation
### From Source
```bash
git clone https://github.com/codemi/firefly-iii-mcp-go.git
cd firefly-iii-mcp-go
make build
```
### Download Binary
Download the pre-built binary for your platform from the [Releases](https://github.com/codemi/firefly-iii-mcp-go/releases) page.
## Getting a Personal Access Token
1. Log in to your Firefly III instance
2. Navigate to **Options > Profile > OAuth**
3. Under "Personal access tokens", click **Create new token**
4. Give it a name (e.g., "MCP Server")
5. Copy the generated token immediately (you won't see it again)
## Usage
### Command Line
```bash
# 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
```
### Server Modes
The server supports two modes:
#### Stdio Mode (Default)
For CLI tools like Claude Desktop that communicate via standard input/output.
```bash
./bin/firefly-mcp --mode stdio
```
#### SSE Mode
HTTP server with Server-Sent Events for web applications.
```bash
./bin/firefly-mcp --mode sse --port 3000
```
Endpoints:
- `GET /sse` - Establish SSE connection
- `POST /message` - Send messages to the server
### Configuration
The configuration is loaded in this priority order:
1. Command-line flags (highest priority)
2. Environment variables
3. `.env` file (lowest priority)
Available options:
| Flag | Env Variable | Default | Description |
|------|--------------|---------|-------------|
| `--baseUrl` | `FIREFLY_III_BASE_URL` | - | Firefly III instance URL |
| `--pat` | `FIREFLY_III_PAT` | - | Personal Access Token |
| `--mode` | `FIREFLY_III_MODE` | `stdio` | Server mode: `stdio` or `sse` |
| `--port` | `FIREFLY_III_PORT` | `3000` | Port for SSE mode |
### With Claude Desktop
Add to your Claude Desktop configuration (`~/.config/claude/claude_desktop_config.json` on Linux or `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
```json
{
"mcpServers": {
"firefly-iii": {
"command": "/path/to/firefly-mcp",
"args": [
"--baseUrl", "https://firefly.example.com",
"--pat", "YOUR_TOKEN"
]
}
}
}
```
Or using environment variables:
```json
{
"mcpServers": {
"firefly-iii": {
"command": "/path/to/firefly-mcp",
"env": {
"FIREFLY_III_BASE_URL": "https://firefly.example.com",
"FIREFLY_III_PAT": "YOUR_TOKEN"
}
}
}
}
```
## Available Tools
### `store_account`
Creates a new account in Firefly III.
**Required parameters:**
- `name` - Account name (e.g., "My Checking Account")
- `type` - Account type: `asset`, `expense`, `revenue`, `cash`, `liability`
**Optional parameters:**
- `iban` - IBAN
- `bic` - BIC/SWIFT code
- `account_number` - Account number
- `opening_balance` - Opening balance (e.g., "1000.00")
- `opening_balance_date` - Date in YYYY-MM-DD format
- `currency_code` - Currency (e.g., "EUR", "USD")
- `account_role` - Role for asset accounts
- `notes` - Additional notes
### `store_transaction`
Creates a new transaction in Firefly III.
**Required parameters:**
- `type` - Transaction type: `withdrawal`, `deposit`, `transfer`
- `description` - Transaction description
- `amount` - Amount (e.g., "25.50")
- `date` - Date in YYYY-MM-DD format
**Optional parameters:**
- `source_name` - Source account name (required for withdrawals/transfers)
- `destination_name` - Destination account name (required for deposits/transfers)
- `category_name` - Category for the transaction
- `currency_code` - Currency code
- `notes` - Additional notes
- `tags` - Comma-separated list of tags
- `apply_rules` - Whether to apply rules (default: true)
### `store_category`
Creates a new category in Firefly III.
**Required parameters:**
- `name` - Category name (e.g., "Groceries")
**Optional parameters:**
- `notes` - Additional notes
### `list_accounts`
Lists all accounts, optionally filtered by type.
**Optional parameters:**
- `type` - Filter by type: `all`, `asset`, `expense`, `revenue`, `cash`, `liability`
### `list_categories`
Lists all categories.
### `list_transactions`
Lists transactions within a date range.
**Optional parameters:**
- `start` - Start date in YYYY-MM-DD format
- `end` - End date in YYYY-MM-DD format
- `type` - Filter by type: `all`, `withdrawal`, `deposit`, `transfer`
## Development
### Build
```bash
make build
```
### Build for all platforms
```bash
make build-all
```
### Run tests
```bash
make test
```
### Clean
```bash
make clean
```
## License
MIT License - see [LICENSE](LICENSE) for details.
## Acknowledgements
Inspired by the [firefly-iii-mcp](https://github.com/etnperlong/firefly-iii-mcp) TypeScript implementation.
