Web automation suite for Firefly III. Includes tools for duplicate detection, subscription analysis, AI-powered categorization, bank imports and transaction enrichment via Amazon/PayPal exports.
Warning
AI-Generated Code Disclosure
This project was implemented entirely by AI coding tools (Claude, Gemini, ChatGPT). The only exception is the logo, which was manually created because AI still sucks at creating logos. While a professional developer supervised the decision-making process, no credit or responsibility is taken for the code itself. Please exercise caution when using this software with your financial data in any environments you do not fully control or trust.
- Toolbox for Firefly III
Identifies potential duplicates by comparing amounts, dates, and descriptions. Grouping is based on a multi-factor confidence score. Review matches and link them directly in Firefly III.
Detects recurring payment patterns (weekly, monthly, quarterly, annual) based on amounts, merchants, and timing. Convert detected patterns into Firefly III recurring transactions.
Suggests categories for uncategorized transactions using OpenAI or Ollama. Matching is done against existing Firefly III categories with confidence scoring and bulk application.
Recommends tags for transactions based on description analysis and your existing tag library.
Enriches transactions with Amazon order details (item names, IDs). Requires JSON export from the Order History Exporter for Amazon extension. Matches by amount and date.
Adds merchant names, emails, and transaction IDs to Firefly III transactions using PayPal CSV activity exports.
Generic CSV import tool with visual column mapping, data transformation rules, and preview. Configurations can be saved for reuse.
Direct import for German banks via FinTS/HBCI. Supports TAN procedures (mobile/push). Requires FinTS product registration.
Important
When FinTS is configured, the server downloads the current German bank index from aqbanking during startup and uses it to populate the bank selector: https://github.com/aqbanking/aqbanking/raw/refs/heads/master/src/libs/plugins/bankinfo/generic/de.tar.bz2
Use the provided compose.yaml:
docker compose up -dBinds to 127.0.0.1:3000. Use a reverse proxy for TLS/Auth.
Requires Node.js 20+.
# Clone the repository
git clone https://github.com/xenolphthalein/toolbox-for-firefly-iii.git
cd toolbox-for-firefly-iii
# Install dependencies
npm install
# Copy and edit the environment file
cp .env.example .env
# Build and start
npm run build
npm startFor development with hot reload:
npm run devNote: Manual execution binds to
0.0.0.0(all interfaces). Ensure port 3000 is firewalled or proxied. Docker binds to localhost by default.
Configuration is handled through environment variables. Copy .env.example to .env and adjust the values for your setup.
| Variable | Description | Default |
|---|---|---|
FIREFLY_API_URL |
URL of your Firefly III instance | Required |
FIREFLY_API_TOKEN |
Firefly III Personal Access Token | Required |
PORT |
Server port | 3000 |
APP_URL |
Public URL (for OAuth callbacks) | http://localhost:3000 |
NODE_ENV |
development or production |
development |
CORS_ORIGINS |
Allowed CORS origins (comma-separated) | Localhost URLs |
Create a Personal Access Token in Firefly III under Profile, OAuth, Personal Access Tokens. See the Firefly III documentation for details.
The toolbox supports multiple authentication methods. In production, authentication is required unless explicitly disabled.
| Variable | Description |
|---|---|
AUTH_METHODS |
Comma-separated list: basic, oidc, firefly, none (e.g., basic,firefly) |
AUTH_SESSION_SECRET |
Session secret (required in production) |
If AUTH_METHODS is not set, all configured methods are auto-detected. Set it explicitly to restrict which methods are shown on the login page.
Basic Authentication
| Variable | Description |
|---|---|
AUTH_BASIC_USERNAME |
Username |
AUTH_BASIC_PASSWORD |
Password |
OIDC (Authentik, Keycloak, etc.)
| Variable | Description |
|---|---|
AUTH_OIDC_ISSUER_URL |
Issuer URL |
AUTH_OIDC_CLIENT_ID |
Client ID |
AUTH_OIDC_CLIENT_SECRET |
Client secret |
AUTH_OIDC_SCOPES |
Scopes (default: openid profile email) |
Firefly III OAuth
| Variable | Description |
|---|---|
AUTH_FIREFLY_CLIENT_ID |
OAuth client ID |
AUTH_FIREFLY_CLIENT_SECRET |
OAuth client secret |
AI features (category and tag suggestions) require either OpenAI or a local Ollama instance.
| Variable | Description | Default |
|---|---|---|
AI_PROVIDER |
openai or ollama |
Auto-detect |
AI_MODEL |
Override model for any provider | - |
OpenAI
| Variable | Description | Default |
|---|---|---|
OPENAI_API_KEY |
API key | - |
OPENAI_API_URL |
API URL (for compatible services) | https://api.openai.com/v1 |
OPENAI_MODEL |
Model name | gpt-4o-mini |
Ollama
| Variable | Description | Default |
|---|---|---|
OLLAMA_API_URL |
Ollama API URL | http://localhost:11434 |
OLLAMA_MODEL |
Model name | llama3.2 |
| Variable | Description | Default |
|---|---|---|
DEFAULT_LOCALE |
Default language: en or de |
Auto-detect from browser |
FINTS_PRODUCT_ID |
FinTS registration ID for German bank imports | - |
FINTS_LOG_REDACTION |
Redact sensitive FinTS payloads from logs. Set to false to disable explicitly. |
true |
LOG_LEVEL |
error, warn, info, or debug |
info |
NUMBER_FORMAT_LOCALE |
Locale for parsing numbers | en-US |
NUMBER_FORMAT_DECIMAL |
Decimal separator | . |
NUMBER_FORMAT_THOUSANDS |
Thousands separator | , |
When running behind a reverse proxy (nginx, Caddy, Traefik), configure the following:
-
Enable TLS on the proxy. Financial data should never travel over plain HTTP.
-
Set
APP_URLto the external URL (e.g.,https://toolbox.example.com). -
Set
CORS_ORIGINSto match the external URL exactly. -
Forward headers for proper protocol detection:
# nginx location / { proxy_pass http://127.0.0.1:3000; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; # Required for SSE streaming proxy_buffering off; proxy_cache off; proxy_read_timeout 86400s; }
-
Disable buffering for Server-Sent Events. The toolbox uses SSE for real-time progress updates during long-running operations. Ensure your proxy does not buffer responses for
/api/*routes.
The toolbox proxies all requests to Firefly III using your API token. A compromised instance means full access to your financial data.
Single-Tenant Architecture
This application is designed for single-tenant use. All users share the same Firefly III API token, meaning everyone who can log in has identical access to all transactions, categories, and tags. This is intentional for households sharing a single budget. If you need per-user access control, deploy separate instances with separate API tokens.
Production Checklist
| Requirement | How |
|---|---|
| Authentication | Set AUTH_METHODS to basic, oidc, firefly, or a combination |
| Session secret | Set AUTH_SESSION_SECRET to a random 32+ character string |
| CORS origins | Set CORS_ORIGINS to your exact frontend URL |
| Network binding | Use the default localhost binding in Docker |
| TLS | Terminate at your reverse proxy |
| Secrets | Store .env with restricted permissions (chmod 600) |
504 Gateway Timeout
Long-running operations may exceed your proxy's default timeout. Increase the read timeout:
proxy_read_timeout 300s;For very large datasets (10,000+ transactions), process in smaller date ranges.
CORS Errors
Ensure CORS_ORIGINS matches your URL exactly without trailing slashes. Set APP_URL when running behind a proxy.
CSRF Token Errors
Add X-Forwarded-Proto header in your proxy configuration and ensure APP_URL matches the actual access URL.
401 Unauthorized from Firefly III
Verify your API token is valid and not expired. Generate a new Personal Access Token in Firefly III if needed.
Connection Refused
If both services run in Docker, use container names instead of localhost:
FIREFLY_API_URL=http://firefly:8080For self-signed certificates, set NODE_EXTRA_CA_CERTS to your CA certificate path.
Contributions are welcome. Please submit PRs to the main branch.
Development Commands
npm run dev # Start development server
npm run build # Production build
npm run typecheck # TypeScript validation
npm run lint # ESLint
npm run format # PrettierThis project is released under the Unlicense, dedicating it to the public domain. You are free to use, modify, and distribute it for any purpose without restrictions.