This server is a full-featured bridge to a Firefly III personal finance instance, letting an AI assistant read, create, update, and delete nearly everything in your finances via 66 tools.
System & accounts: check the Firefly III version/connectivity (get_about), and list, view, create, update, or delete asset, expense, revenue, and liability accounts (with roles, currencies, opening balances, credit card settings).
Transactions: list, retrieve, create withdrawals/deposits/transfers, build split transactions with a group title, update details/tags/categories, delete, and search.
Budgets: manage budgets and their monetary limits per period, including listing and deleting limits.
Automation: manage rules and rule groups (including manually triggering a rule group) and webhooks.
Recurring transactions: list, view, create, update, and delete recurring transaction rules.
Bills & piggy banks: track bills (create/list/delete) and savings goals, including adding or removing money from a piggy bank.
Currencies & preferences: manage currencies (list, get, create, update, delete) and read/update user preferences.
Attachments & insights: upload base64 files to objects like transaction journals, list/get/delete attachments, and pull balance-trend charts, net worth summaries, and per-category spending summaries for a date range.
Categories, tags & object groups: create and list categories and tags, and organize accounts/piggy banks into object groups.
Admin: trigger a CSV or JSON data export for a date range.
Provides comprehensive API coverage for interacting with a Firefly III personal finance instance, including tools for managing accounts, transactions, budgets, bills, recurring rules, automation, attachments, currencies, insights, and more.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Universal Firefly III AI Bridge Show my recent expenses"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A professional-grade, AI-agnostic bridge providing exhaustive 100% API coverage for connecting AI assistants to your Firefly III personal finance instance.
66 tools covering every major Firefly III capability: accounts, transactions, budgets, bills, recurring rules, automation, insights, attachments, currencies, and more.
AI Platform | Protocol | Connection | Setup Guide |
Claude Code | MCP (Native) | stdio | |
Claude Desktop | MCP (Native) | stdio | |
Gemini CLI | MCP Extension | stdio | |
Cursor / VS Code | MCP | stdio or SSE | Manual setup below |
ChatGPT | OpenAPI Actions | REST / JSON |
|
Custom Apps | REST API | HTTP |
|
Related MCP server: YNAB Assistant
Node.js v18 or later
A running Firefly III instance
A Personal Access Token from Firefly III
(Profile → OAuth → Personal Access Tokens → Create new token)
git clone https://github.com/fabianonetto/mcp-server-firefly-iii.git
cd mcp-server-firefly-iii
npm installClaude Code uses .mcp.json in the project directory for MCP server configuration. Credentials go in a separate .env file so no secrets are ever in config files.
1. Create .env in the repo root (gitignored — never committed):
FIREFLY_URL=http://your-host:PORT
FIREFLY_TOKEN=your_personal_access_tokenGet your token: Firefly III → Profile → OAuth → Personal Access Tokens → Create new token
2. Create .mcp.json in the repo root (gitignored — never committed):
{
"mcpServers": {
"firefly-iii": {
"command": "node",
"args": ["./index.js"]
}
}
}The server reads credentials from .env automatically. No secrets in .mcp.json.
3. Start Claude Code from the repo directory:
claudeThe server starts automatically. Claude Code will prompt you to approve it on first launch (once only).
4. Verify the connection by asking:
Use the get_about toolYou should receive your Firefly III version and API information.
Using from other projects:
Copy both .env and .mcp.json to any other project directory, changing ./index.js to the absolute path:
"args": ["/absolute/path/to/mcp-server-firefly-iii/index.js"]See CLAUDE.md for the full guide including auto-approval configuration.
Add the server to your Claude Desktop config file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"firefly-iii": {
"command": "node",
"args": ["/absolute/path/to/mcp-server-firefly-iii/index.js"],
"env": {
"FIREFLY_URL": "http://your-host:PORT",
"FIREFLY_TOKEN": "your_personal_access_token"
}
}
}
}Restart Claude Desktop after saving.
gemini extensions install https://github.com/fabianonetto/mcp-server-firefly-iiiThen configure your instance:
gemini config set extensions.firefly-iii-universal-bridge.settings.FIREFLY_URL "http://your-host:PORT"
gemini config set extensions.firefly-iii-universal-bridge.settings.FIREFLY_TOKEN "your_token"See gemini.md for the full guide.
The official image is available on GitHub Packages: ghcr.io/fabianonetto/mcp-server-firefly-iii.
Ideal for ChatGPT Actions, Cursor (SSE), or custom integrations.
docker run -d \
--name firefly-mcp \
-p 3001:3001 \
-e FIREFLY_URL="http://your-firefly-instance" \
-e FIREFLY_TOKEN="your_personal_access_token" \
-e PORT=3001 \
ghcr.io/fabianonetto/mcp-server-firefly-iii:latestAdd this to your claude_desktop_config.json:
{
"mcpServers": {
"firefly-iii": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e", "FIREFLY_URL=http://your-host:PORT",
"-e", "FIREFLY_TOKEN=your_token",
"ghcr.io/fabianonetto/mcp-server-firefly-iii:latest"
]
}
}
}Add to your MCP config (.cursor/mcp.json or equivalent):
{
"mcpServers": {
"firefly-iii": {
"command": "node",
"args": ["/absolute/path/to/mcp-server-firefly-iii/index.js"],
"env": {
"FIREFLY_URL": "http://your-host:PORT",
"FIREFLY_TOKEN": "your_personal_access_token"
}
}
}
}Start the server with a port to enable the MCP HTTP endpoints and REST API:
FIREFLY_URL=http://your-host:PORT FIREFLY_TOKEN=your_token PORT=3000 node index.jsAvailable endpoints:
Endpoint | Description |
| Streamable HTTP transport (recommended for modern MCP clients like n8n) |
| Server-Sent Events (SSE) transport (supports multiple concurrent sessions & reconnects) |
| SSE message endpoint (routes by |
| Direct REST call to any tool |
| OpenAPI 3.0 spec (import into ChatGPT Actions) |
Category | Tools | Description |
Core | 1 | System info & connectivity |
Accounts | 5 | Full CRUD for all account types |
Transactions | 7 | CRUD, split transactions, search |
Budgets | 8 | Budgets + monetary limits |
Bills & Piggy Banks | 7 | Bill tracking + savings goals |
Automation | 11 | Rules, rule groups, webhooks |
Recurring | 5 | Recurring transaction rules |
System | 8 | Currencies + user preferences |
Insights | 7 | Attachments, charts, net worth, spending |
Meta | 4 | Categories + tags |
Object Groups | 2 | Account/piggy bank organization |
Admin | 1 | Data export |
Total | 66 |
Document | Description |
Complete reference for all 66 tools and their input schemas | |
Prompt examples for common financial tasks | |
Strategic guides: tax assistant, subscription auditor, receipt manager | |
Test suite documentation (78 tests, all tools covered) | |
Claude Code & Claude Desktop setup guide | |
Gemini CLI extension guide |
npm test78 tests covering all 66 tools. No live Firefly III instance required — all API calls are mocked. See docs/TESTING.md for details.
Use a VPN or SSH tunnel if exposing the server to the internet.
Keep your FIREFLY_TOKEN secret. Never commit .mcp.json or .env files.
See SECURITY.md for the full security policy.
v1.x — Initial connectivity
v2.x — Exhaustive API coverage (CRUD & core admin)
v3.x — Power user features (splits, insights, automation)
v3.1.0 — Official Docker image & CI/CD
Create a new account.
Inputs: name (required), type (required), account_role, currency_code, +4 more.
Create a new bill.
Inputs: date (required), name (required), amount_max (required), amount_min (required), +1 more.
Create a new budget.
Inputs: name (required).
Set a monetary limit for a budget period.
Inputs: id (required), end (required), start (required), amount (required), +1 more.
Create a new category.
Inputs: name (required).
Store a new currency.
Inputs: code (required), name (required), symbol (required), decimal_places.
Create a new object group.
Inputs: title (required), order.
Create a new piggy bank.
Inputs: name (required), account_id (required), target_amount (required).
Create a new recurring transaction rule.
Inputs: name (required), type (required), amount (required), repeat_freq (required), +2 more.
Store a new rule.
Inputs: title (required), trigger (required), rule_group_id (required).
Create a single transaction divided into multiple splits (e.g., one receipt with different categories).
Inputs: splits (required), group_title.
Create a new tag.
Inputs: tag (required).
Create a simple withdrawal, deposit, or transfer.
Inputs: type (required), amount (required), description (required), source_name (required), +4 more.
Create a webhook.
Inputs: url (required), title (required), trigger (required).
Permanently delete an account.
Inputs: id (required).
Delete an attachment.
Inputs: id (required).
Delete a bill.
Inputs: id (required).
Delete a budget.
Inputs: id (required).
Delete a budget limit.
Inputs: limit_id (required), budget_id (required).
Delete a currency.
Inputs: code (required).
Delete a piggy bank.
Inputs: id (required).
Delete a recurring transaction rule.
Inputs: id (required).
Delete a rule.
Inputs: id (required).
Permanently delete a transaction.
Inputs: id (required).
Delete a webhook.
Inputs: id (required).
Get system information from Firefly III.
Inputs: no named parameters.
Get a single account by ID.
Inputs: id (required).
Get balance trend charts.
Inputs: end (required), start (required).
Get attachment metadata.
Inputs: id (required).
Get a single budget by ID.
Inputs: id (required).
Get a single currency by code.
Inputs: code (required).
Get pre-calculated net worth summary over time.
Inputs: end (required), start (required).
Get a specific preference.
Inputs: name (required).
Get a single recurring transaction by ID.
Inputs: id (required).
Get a single rule.
Inputs: id (required).
Get a single rule group.
Inputs: id (required).
Get expense totals per category for a date range.
Inputs: end (required), start (required).
Get a single transaction by ID.
Inputs: id (required).
List all accounts.
Inputs: type.
List all files.
Inputs: no named parameters.
List all bills.
Inputs: no named parameters.
List monetary limits for a budget.
Inputs: id (required).
List all budgets.
Inputs: no named parameters.
List all categories.
Inputs: no named parameters.
List all currencies.
Inputs: no named parameters.
List all object groups (used for organizing accounts/piggy banks).
Inputs: no named parameters.
List all piggy banks.
Inputs: no named parameters.
List all user preferences.
Inputs: no named parameters.
List all recurring transaction rules.
Inputs: no named parameters.
List all rule groups.
Inputs: no named parameters.
List all automation rules.
Inputs: no named parameters.
List all tags.
Inputs: no named parameters.
List recent transactions.
Inputs: limit.
List webhooks.
Inputs: no named parameters.
Search for transactions.
Inputs: query (required), limit.
Trigger a data export from Firefly III.
Inputs: end (required), start (required), type.
Manually run rule group.
Inputs: id (required).
Update an existing account.
Inputs: id (required), name, active.
Update a budget.
Inputs: id (required), name, active.
Update an existing currency.
Inputs: code (required), enabled.
Add/remove money from goal.
Inputs: id (required), amount (required).
Update a specific preference.
Inputs: data (required), name (required).
Update an existing recurring transaction.
Inputs: id (required), name, active.
Update a rule.
Inputs: id (required), title.
Update an existing transaction. Supports updating description, category_name, and other fields.
Inputs: id (required), tags, description, category_name.
Upload a file and attach it to a Firefly III object (e.g. a transaction). Requires two steps internally: creates the attachment record, then uploads the file content.
Inputs: content (required), filename (required), attachable_id (required), attachable_type (required).
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 66 tools
Every tool maps to a distinct resource and action, and similar-sounding tools like get_account vs get_account_overview_chart are clearly separated by descriptions. Even create_transaction and create_split_transaction are differentiated as simple vs split creation.
Tool names consistently follow a lowercase snake_case verb_noun pattern such as list_accounts, get_account, create_account, update_account, and delete_account. Minor exceptions like get_about and create_split_transaction do not undermine the overall predictable convention.
With 66 tools, the surface is far too large for an AI-facing server; even though Firefly III has a broad API, this feels like an uncurated endpoint dump rather than a focused bridge. The volume creates significant context overhead and tool-selection burden for agents.
Core resources like accounts, transactions, budgets, rules, and recurring transactions have full CRUD coverage, but many secondary resources are notably incomplete: categories only have list/create, bills lack get/update, rule groups have no create/update/delete, and webhooks/object groups are partial. These gaps will cause frequent agent dead ends.
Personal finance for AI agents: accounts, budgets, goals, 9-strategy debt payoff, reports. OAuth 2.1
Read-only personal finance for AI agents: budgets, receipts, net worth, bills. OAuth 2.1.
Log, query, and edit expenses, budgets, and accounts in Manilo (formerly Ledgy) from any MCP-compatible AI assistant.
Household finance memory, budgets, transactions, and monthly reviews for AI assistants.
