Provides tools for managing personal finances in Firefly III, including creating and tracking transactions (withdrawals, deposits, transfers), managing accounts, categories, budgets, and tags, with support for querying balances and financial history.
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., "@Firefly III MCP Server I spent $45 on groceries at Trader Joe's"
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.
An MCP (Model Context Protocol) server that gives Claude full access to your Firefly III personal finance instance. Talk to Claude in natural language to record expenses, check balances, manage budgets, and more.
Transactions: Create, list, search, update, and delete transactions (withdrawals, deposits, transfers)
Accounts: Manage asset, expense, revenue, liability, and cash accounts
Categories: Organize transactions with categories
Budgets: Create and manage budgets with auto-budget support
Tags: Label transactions with flexible tags
Related MCP server: Firefly III MCP Server
Node.js >= 18
A running Firefly III instance
A Personal Access Token (PAT) from your Firefly III instance
Log into your Firefly III instance
Go to Options → Profile → OAuth
Under Personal Access Tokens, create a new token
Copy the token — you'll need it for configuration
npm install -g firefly-iii-mcp-servergit clone https://github.com/przbadu/firefly-iii-mcp-server.git
cd firefly-iii-mcp-server
npm install
npm run buildEdit your Claude Desktop config file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Using the npm-installed binary:
{
"mcpServers": {
"firefly-iii": {
"command": "firefly-iii-mcp-server",
"env": {
"FIREFLY_III_URL": "https://your-firefly-instance.example.com",
"FIREFLY_III_PAT": "your-personal-access-token-here"
}
}
}
}Or using npx (no global install needed):
{
"mcpServers": {
"firefly-iii": {
"command": "npx",
"args": ["-y", "firefly-iii-mcp-server"],
"env": {
"FIREFLY_III_URL": "https://your-firefly-instance.example.com",
"FIREFLY_III_PAT": "your-personal-access-token-here"
}
}
}
}claude mcp add firefly-iii \
-e FIREFLY_III_URL=https://your-firefly-instance.example.com \
-e FIREFLY_III_PAT=your-personal-access-token-here \
-- npx -y firefly-iii-mcp-serverOr add it to your .claude/settings.json:
{
"mcpServers": {
"firefly-iii": {
"command": "npx",
"args": ["-y", "firefly-iii-mcp-server"],
"env": {
"FIREFLY_III_URL": "https://your-firefly-instance.example.com",
"FIREFLY_III_PAT": "your-personal-access-token-here"
}
}
}
}Once configured, just talk to Claude naturally:
"I spent $45.50 at Trader Joe's on groceries today"
"Record a $2,500 salary deposit from my employer into my checking account"
"Transfer $500 from Checking to Savings"
"Show me all my transactions from last week"
"How much did I spend on restaurants this month?"
"What's the balance of my checking account?"
"Create a monthly grocery budget of $600"
"List all my expense categories"
"Tag my last 3 restaurant transactions as 'business meals'"
Tool | Description |
| Create withdrawal, deposit, or transfer |
| List transactions with filters |
| Get transaction details by ID |
| Update an existing transaction |
| Delete a transaction |
| Search with Firefly III query syntax |
| Create a new account |
| List accounts by type |
| Get account details |
| Update account properties |
| Delete an account |
| List all categories |
| Create a category |
| Update a category |
| Delete a category |
| List all budgets |
| Create a budget |
| Update a budget |
| Delete a budget |
| List all tags |
| Create a tag |
| Update a tag |
| Delete a tag |
# Watch mode with auto-reload
npm run dev
# Build for production
npm run build
# Run the built server
npm startMIT
Create a new account in Firefly III.
Account types: asset (bank accounts, wallets), expense (stores, services), revenue (employers, income sources), liability (loans, mortgages), cash.
For asset accounts, specify a role: defaultAsset, sharedAsset, savingAsset, ccAsset (credit card), cashWalletAsset.
Inputs: name (required), type (required), currency_code, account_role, +7 more.
Create a new budget. Budgets help you track spending limits.
Auto-budget options:
'reset': Budget resets to the set amount each period
'rollover': Unused budget rolls over to the next period
'none': Manual budgeting only
Inputs: name (required), active, auto_budget_type, auto_budget_amount, +3 more.
Create a new transaction category.
Inputs: name (required), notes.
Create a new tag for labeling transactions.
Inputs: tag (required), description.
Create a new transaction in Firefly III.
Supports withdrawals (expenses), deposits (income), and transfers between accounts.
For a withdrawal: provide source_name (your asset account, e.g. "Checking Account") and destination_name (the expense account, e.g. "Supermarket"). For a deposit: provide source_name (revenue account, e.g. "Employer") and destination_name (your asset account). For a transfer: both source and destination should be your own asset accounts.
If an expense/revenue account doesn't exist yet, Firefly III will auto-create it.
Returns: The created transaction with its ID.
Inputs: type (required), description (required), date (required), amount (required), +10 more.
Permanently delete an account. All linked transactions will also be deleted. This cannot be undone.
Inputs: id (required).
Delete a budget. Transactions linked to this budget will have their budget cleared.
Inputs: id (required).
Delete a category. Transactions using this category will have their category cleared.
Inputs: id (required).
Delete a tag. It will be removed from all transactions that use it.
Inputs: tag (required).
Permanently delete a transaction by its ID. This action cannot be undone.
Inputs: id (required).
Get a single account by ID with full details.
Inputs: id (required).
Get a single transaction by its ID. Returns full details including all splits.
Inputs: id (required).
List accounts with optional type filter. Returns account names, balances, and types.
Inputs: type, limit, page.
List all budgets with their auto-budget configuration.
Inputs: limit, page.
List all categories. Use categories to classify transactions (e.g. Groceries, Rent, Entertainment).
Inputs: limit, page.
List all tags. Tags are flexible labels you can attach to transactions.
Inputs: limit, page.
List transactions from Firefly III with optional filters.
Supports filtering by type (withdrawal, deposit, transfer), date range, and pagination. Returns a paginated list of transactions with key details.
Inputs: limit, page, type, start, +1 more.
Search transactions using Firefly III's query syntax.
Simple text searches match against description. Advanced syntax includes:
description_contains:grocery
amount_more:50
amount_less:200
date_after:2024-01-01
date_before:2024-12-31
category_is:Food
tag_is:vacation
source_account_is:Checking
destination_account_is:Supermarket
Combine multiple filters with spaces.
Inputs: query (required), limit, page.
Update an existing account. Only provide fields you want to change.
Inputs: id (required), name, active, account_role, +2 more.
Update an existing budget's name, status, or notes.
Inputs: id (required), name, active, notes.
Update an existing category's name or notes.
Inputs: id (required), name, notes.
Update an existing tag's description.
Inputs: tag (required), description.
Update an existing transaction. Only provide the fields you want to change.
First use firefly_get_transaction to retrieve the current values, then pass only the changed fields here.
Inputs: id (required), description, date, amount, +6 more.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Scored across 23 tools
Each tool targets a distinct resource-action combination (create/list/get/update/delete/search for transactions and accounts; list/create/update/delete for categories, budgets, and tags). There is no meaningful overlap, and list vs. search transactions are clearly differentiated by search's advanced query syntax.
All tools follow the same `firefly_<verb>_<noun>` snake_case pattern, using a consistent set of verbs: create, list, get, update, delete, search. This makes the API highly predictable and easy to navigate.
At 23 tools, this exceeds the typical 3-15 sweet spot, but each tool maps to a specific operation on one of five core resources (transactions, accounts, categories, budgets, tags). The count is slightly heavy but justified given the breadth of Firefly III's domain.
The surface covers full CRUD for accounts and transactions, plus search for transactions, and reasonable create/list/update/delete coverage for categories, budgets, and tags. Minor gaps include the absence of dedicated get-by-ID operations for categories, budgets, and tags, and no support for advanced Firefly III features like rules or recurring transactions, but core workflows are solid.
Log, query, and edit expenses, budgets, and accounts in Manilo from any MCP-compatible AI assistant.
Log, query, and edit expenses, budgets, and accounts in Manilo (formerly Ledgy) from any MCP-compatible AI assistant.
Personal finance by conversation: expenses, receipts, statement import, budgets, net worth.
Log, query, and edit expenses, budgets, and accounts in Ledgy from any MCP-compatible AI assistant.
