Which integrations are available for this server?

Provides tools for interacting with Firefly III's API, enabling management of accounts, transactions, categories, tags, budgets, bills, piggy banks, recurrences, currencies, rules, search, reports, and attachments in a Firefly III instance.

How do I use firefly-iii-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@firefly-iii-mcp Show my spending by category for this month" 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.

firefly-iii-mcp

by braindaamage

Overview Schema Related Servers Score Discussions

TypeScript

Hybrid

firefly-iii-mcp

An MCP (Model Context Protocol) server for Firefly III, exposing 114 tools across 13 resource categories so AI agents (Claude, Cursor, etc.) can manage your personal finances directly.

Features

114 tools covering every major Firefly III resource
Dual transport: stdio (Claude Desktop) and Streamable HTTP (remote / multi-client)
Docker-first: single-image deployment, no external dependencies beyond Firefly III
Full Firefly III v6 support: piggy-bank v6 API, recurrences v6, exchange rates v6
Optional HTTP auth via bearer token (MCP_AUTH_TOKEN)
TypeScript with strict types, ES2022, Node 22

Related MCP server: Firefly III MCP Server

Requirements

Requirement	Version
Node.js	22+
Firefly III	v6.x (tested on v6.5.9)
npm	10+

Installation

# Clone
git clone https://github.com/your-org/firefly-iii-mcp.git
cd firefly-iii-mcp

# Install dependencies
npm ci

# Build
npm run build

Configuration

All configuration is via environment variables.

Variable	Required	Default	Description
`FIREFLY_BASE_URL`	Yes	—	Base URL of your Firefly III instance, e.g. `http://localhost:8080`
`FIREFLY_API_TOKEN`	Yes	—	Personal access token from Firefly III → Profile → OAuth → Personal Access Tokens
`TRANSPORT`	No	`http`	Transport mode: `stdio` or `http`
`PORT`	No	`3000`	HTTP server port (HTTP transport only)
`HOST`	No	`0.0.0.0`	HTTP server bind host (HTTP transport only)
`MCP_AUTH_TOKEN`	No	—	Bearer token required on `Authorization` header for all HTTP requests. Leave unset to disable auth
`FIREFLY_API_TIMEOUT`	No	`30000`	Firefly III API request timeout in milliseconds
`MAX_PAGE_FETCH`	No	`10`	Maximum pages to auto-fetch when listing resources
`LOG_LEVEL`	No	`info`	Log verbosity: `debug`, `info`, `warn`, `error`
`FIREFLY_TOOL_PROFILE`	No	`default`	Tool profile controlling which of the 114 tools are exposed. See Tool Profiles

Create a .env file for local development:

cp .env.example .env
# Edit FIREFLY_BASE_URL and FIREFLY_API_TOKEN

Usage

Claude Desktop — stdio transport

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "firefly-iii": {
      "command": "node",
      "args": ["/absolute/path/to/firefly-iii-mcp/dist/index.js"],
      "env": {
        "FIREFLY_BASE_URL": "http://localhost:8080",
        "FIREFLY_API_TOKEN": "your-personal-access-token",
        "TRANSPORT": "stdio"
      }
    }
  }
}

Restart Claude Desktop. The 114 Firefly III tools will be available in every conversation.

Claude Desktop — remote HTTP transport

Claude Desktop only supports stdio-based servers natively. To connect to a remote MCP server over HTTP, use the mcp-remote bridge:

{
  "mcpServers": {
    "firefly-iii": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://your-mcp-server.example.com/mcp"
      ]
    }
  }
}

If the server requires authentication (MCP_AUTH_TOKEN), pass the headers flag:

{
  "mcpServers": {
    "firefly-iii": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://your-mcp-server.example.com/mcp",
        "--header",
        "Authorization: Bearer your-mcp-auth-token"
      ]
    }
  }
}

Restart Claude Desktop after saving.

Claude.ai — remote HTTP transport

On claude.ai, remote MCP servers are configured as connectors:

Go to Settings > Connectors
Click Add custom connector
Enter the server URL: https://your-mcp-server.example.com/mcp
Configure authentication if required
Set tool permissions

Docker — HTTP transport

Build:

docker build -t firefly-iii-mcp .

Run (HTTP, stateless):

docker run -d \
  -p 3000:3000 \
  -e FIREFLY_BASE_URL=http://your-firefly-host:8080 \
  -e FIREFLY_API_TOKEN=your-token \
  -e MCP_AUTH_TOKEN=your-mcp-secret \
  -e FIREFLY_TOOL_PROFILE=default \
  -e LOG_LEVEL=info \
  firefly-iii-mcp

MCP endpoint: POST http://localhost:3000/mcp Health check: GET http://localhost:3000/health

Run (stdio via Docker):

docker run --rm -i \
  -e FIREFLY_BASE_URL=http://your-firefly-host:8080 \
  -e FIREFLY_API_TOKEN=your-token \
  -e TRANSPORT=stdio \
  -e FIREFLY_TOOL_PROFILE=default \
  firefly-iii-mcp

docker-compose — Local development stack

docker-compose.dev.yml spins up a complete local stack: MariaDB, Firefly III, and the MCP server in development (hot-reload) mode.

# Start everything (MariaDB → Firefly III → MCP)
FIREFLY_API_TOKEN=your-token FIREFLY_TOOL_PROFILE=default docker compose -f docker-compose.dev.yml up

# Stop
docker compose -f docker-compose.dev.yml down

Services:

Service	Port	Description
`firefly-db`	—	MariaDB database for Firefly III
`firefly-iii`	`8080`	Firefly III web UI & API
`firefly-mcp`	`3000`	MCP server (hot-reload via `tsx watch`)

After startup, open Firefly III at http://localhost:8080 to create your account and generate a personal access token. Set FIREFLY_API_TOKEN accordingly.

Tool Profiles

The FIREFLY_TOOL_PROFILE environment variable controls which tools are exposed to the AI. This keeps the LLM context focused on what's relevant for your workflow.

The 7 presets

Preset	Tools	Best for
`minimal`	26	Read-only queries: balances, transactions, reports
`default`	62	Daily expense management (default when unset)
`reporting`	64	Financial analysis, dashboards, auditing — zero writes
`budget`	39	Budget tracking and management
`automation`	39	Configuring rules and recurring transactions
`admin`	32	System administration: accounts, currencies, attachments
`full`	114	Unrestricted access to all tools

The 15 categories

Each category supports two access levels: read-only (default) and write (includes read).

Category	Read tools	Write tools (additional)	Total
`accounts`	list, get, transactions	create, update, delete	6
`transactions`	list, get, journals_get	create, update, delete, journals_delete	7
`categories`	list, get, transactions	create, update, delete	6
`tags`	list, get, transactions	create, update, delete	6
`budgets`	list, get, transactions, limits_list	create, update, delete, limits_create, limits_update, limits_delete	10
`bills`	list, get, transactions, rules	create, update, delete	7
`piggy_banks`	list, get, events	create, update, delete	6
`recurrences`	list, get	create, update, delete, trigger	6
`currencies`	list, get, get_primary	enable, disable, set_primary, create, update, delete	9
`exchange_rates`	list, get	create	3
`rules`	list, get, groups_list, groups_get, groups_rules	create, update, delete, test, trigger, groups_create, groups_update, groups_delete, groups_test, groups_trigger	15
`search`	search_transactions, search_accounts	(read-only)	2
`autocomplete`	9 autocomplete tools	(read-only)	9
`reports`	15 report and chart tools	(read-only)	15
`attachments`	list, get, download	create, update, delete, upload	7

Composition

Tokens are combined with union semantics — the highest access level wins per category:

# Single preset
FIREFLY_TOOL_PROFILE=minimal

# Preset + extra write access
FIREFLY_TOOL_PROFILE=default,bills:write        # 65 tools
FIREFLY_TOOL_PROFILE=default,budgets:write       # 68 tools

# Combine two presets
FIREFLY_TOOL_PROFILE=budget,automation           # 67 tools

# Custom category mix
FIREFLY_TOOL_PROFILE=accounts:write,transactions:write,reports

# Read-only analysis + ability to record transactions
FIREFLY_TOOL_PROFILE=reporting,transactions:write  # 68 tools

Rules:

category without suffix → read-only access
category:write → read + write access
Multiple tokens are unioned; higher level wins per category
Invalid tokens log a warning and are ignored
If all tokens are invalid → falls back to default
Unset variable → default (62 tools)

Claude Desktop example

{
  "mcpServers": {
    "firefly-iii": {
      "command": "node",
      "args": ["/path/to/firefly-iii-mcp/dist/index.js"],
      "env": {
        "FIREFLY_BASE_URL": "http://localhost:8080",
        "FIREFLY_API_TOKEN": "your-token",
        "TRANSPORT": "stdio",
        "FIREFLY_TOOL_PROFILE": "default"
      }
    }
  }
}

Tools Reference

Accounts (6 tools)

Tool	Description
`accounts_list`	List accounts; filter by type (asset, expense, revenue, liability, cash)
`accounts_get`	Get a single account by ID
`accounts_create`	Create a new account
`accounts_update`	Update an existing account
`accounts_delete`	Delete an account (irreversible)
`accounts_transactions`	List transactions for an account; supports date range and type filters

Transactions (7 tools)

Tool	Description
`transactions_list`	List transactions; filter by date range, type, page
`transactions_get`	Get a transaction group (all splits) by ID
`transactions_create`	Create a transaction (single or split); supports multi-currency
`transactions_update`	Update a transaction group; use `transaction_journal_id` to target splits
`transactions_delete`	Delete an entire transaction group (irreversible)
`transaction_journals_get`	Get a single transaction split by journal ID
`transaction_journals_delete`	Delete a single split from a multi-split transaction

Categories (6 tools)

Tool	Description
`categories_list`	List all categories
`categories_get`	Get a category by ID
`categories_create`	Create a category
`categories_update`	Update a category
`categories_delete`	Delete a category
`categories_transactions`	List transactions for a category; supports date range

Tags (6 tools)

Tool	Description
`tags_list`	List all tags
`tags_get`	Get a tag by tag string
`tags_create`	Create a tag
`tags_update`	Update a tag
`tags_delete`	Delete a tag
`tags_transactions`	List transactions for a tag

Rules & Rule Groups (15 tools)

Tool	Description
`rule_groups_list`	List all rule groups
`rule_groups_get`	Get a rule group by ID
`rule_groups_create`	Create a rule group
`rule_groups_update`	Update a rule group
`rule_groups_delete`	Delete a rule group
`rule_groups_rules`	List rules within a group
`rule_groups_test`	Test all rules in a group against existing transactions (dry-run)
`rule_groups_trigger`	Apply all rules in a group to existing transactions
`rules_list`	List all rules
`rules_get`	Get a rule by ID
`rules_create`	Create a rule with triggers and actions
`rules_update`	Update a rule
`rules_delete`	Delete a rule
`rules_test`	Test a rule against existing transactions (dry-run)
`rules_trigger`	Apply a rule to existing transactions

Budgets & Budget Limits (10 tools)

Tool	Description
`budgets_list`	List all budgets; optional date range for spending info
`budgets_get`	Get a budget by ID
`budgets_create`	Create a budget; supports auto-budget (reset/rollover/adjusted)
`budgets_update`	Update a budget
`budgets_delete`	Delete a budget
`budgets_transactions`	List transactions assigned to a budget
`budget_limits_list`	List spending limits for a budget
`budget_limits_create`	Create a spending limit for a date period
`budget_limits_update`	Update a spending limit
`budget_limits_delete`	Delete a spending limit

Piggy Banks (6 tools)

Tool	Description
`piggy_banks_list`	List all piggy banks
`piggy_banks_get`	Get a piggy bank by ID
`piggy_banks_create`	Create a piggy bank linked to an asset account
`piggy_banks_update`	Update a piggy bank
`piggy_banks_delete`	Delete a piggy bank
`piggy_banks_events`	List events (deposits/withdrawals) for a piggy bank

Bills (7 tools)

Tool	Description
`bills_list`	List all bills
`bills_get`	Get a bill by ID
`bills_create`	Create a bill
`bills_update`	Update a bill
`bills_delete`	Delete a bill
`bills_transactions`	List transactions linked to a bill
`bills_rules`	List rules linked to a bill

Recurrences (6 tools)

Tool	Description
`recurrences_list`	List all recurring transactions
`recurrences_get`	Get a recurring transaction by ID
`recurrences_create`	Create a recurring transaction
`recurrences_update`	Update a recurring transaction
`recurrences_delete`	Delete a recurring transaction
`recurrences_trigger`	Trigger recurrence processing (runs the cron job)

Currencies & Exchange Rates (12 tools)

Tool	Description
`currencies_list`	List all currencies
`currencies_get`	Get a currency by code
`currencies_create`	Create a custom currency
`currencies_update`	Update a currency
`currencies_delete`	Delete a currency
`currencies_enable`	Enable a currency
`currencies_disable`	Disable a currency
`currencies_set_primary`	Set a currency as the default
`currencies_get_primary`	Get the current default currency
`exchange_rates_list`	List available exchange rate pairs
`exchange_rates_get`	Get the exchange rate between two currencies
`exchange_rates_create`	Create a manual exchange rate

Search & Autocomplete (11 tools)

Tool	Description
`search_transactions`	Full-text search across transactions; supports operators like `amount_more:`, `category_is:`, `date_after:`, etc.
`search_accounts`	Full-text search across accounts
`autocomplete_accounts`	Account name autocomplete
`autocomplete_categories`	Category name autocomplete
`autocomplete_tags`	Tag autocomplete
`autocomplete_budgets`	Budget name autocomplete
`autocomplete_bills`	Bill name autocomplete
`autocomplete_currencies`	Currency autocomplete
`autocomplete_piggy_banks`	Piggy bank name autocomplete
`autocomplete_rules`	Rule title autocomplete
`autocomplete_descriptions`	Transaction description autocomplete

Reports & Charts (15 tools)

Tool	Description
`reports_summary`	Overall financial summary for a date range
`reports_expense_by_category`	Expenses grouped by category
`reports_expense_by_budget`	Expenses grouped by budget
`reports_expense_by_account`	Expenses grouped by account
`reports_expense_by_tag`	Expenses grouped by tag
`reports_expense_by_bill`	Expenses grouped by bill
`reports_expense_total`	Total expenses for a period
`reports_income_by_category`	Income grouped by category
`reports_income_by_account`	Income grouped by account
`reports_income_by_tag`	Income grouped by tag
`reports_income_total`	Total income for a period
`reports_transfer_total`	Total transfers for a period
`charts_account_overview`	Account balance chart data
`charts_budget_overview`	Budget spending chart data
`charts_category_overview`	Category spending chart data

Attachments (7 tools)

Tool	Description
`attachments_list`	List all attachments
`attachments_get`	Get an attachment by ID
`attachments_create`	Create an attachment record linked to a transaction or other object
`attachments_update`	Update an attachment record
`attachments_delete`	Delete an attachment
`attachments_upload`	Upload file content for an attachment (base64)
`attachments_download`	Download attachment content (returns base64)

Development

# Run in dev mode (hot reload)
npm run dev

# Run unit tests (requires .env.test with a live Firefly III instance)
npm test

# Run E2E tests
npm run test:e2e

# Lint
npm run lint

# Type-check
npx tsc --noEmit

License

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

This server cannot be installed

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

license - permissive license

Not graded

quality - not tested

maintenance

How are these scores calculated?

Maintenance

UpdatingMaintainers

UpdatingResponse time

–Release cycle

0Releases (12mo)

Commit activity

Resources

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Servers

Firefly III MCP Server
Finance Agent Orchestration
boxpositron
-
license
Not graded
quality
Not graded
maintenance
Enables AI tools to interact with Firefly III personal finance management instances through a cloud-deployed MCP server. Supports financial operations like account management, transactions, budgeting, and reporting with configurable tool presets.
Updated a year ago (2025-08-19 01:49 UTC)
29
Firefly III MCP Server
Finance App Automation Developer Tools
dmitos
A
license
Not graded
quality
C
maintenance
Enables interaction with Firefly III personal finance management instances via the Firefly III API, deployed as a Cloudflare Worker. It allows AI tools to manage transactions, accounts, budgets, and reporting through natural language.
Updated 5 months ago (2026-03-21 01:02 UTC)
29
ISC
Universal Firefly III AI
Finance
fabianonetto
A
license
Not graded
quality
D
maintenance
Provides comprehensive AI-agnostic access to all Firefly III personal finance features via 66 tools, enabling natural language management of accounts, transactions, budgets, and more.
Updated 4 months ago (2026-05-05 02:16 UTC)
13
23
MIT
firefly-iii-mcp-server
Xerrion
A
license
Not graded
quality
A
maintenance
Enables AI agents to manage personal finances through Firefly III, supporting tasks like recording transactions, managing budgets, and generating financial summaries.
Updated a month ago (2026-07-21 08:50 UTC)
14
MIT

View all related MCP servers

Related MCP Connectors

BankSync
Connect AI agents to bank accounts, transactions, balances, and investments.
Agent402.Tools: pay-per-call web tools
Agentic Finance: 500+ tools for AI agents over x402 or MPP, free via PoW, or prepaid card credits
0nMCP — Universal AI API Orchestrator
Universal AI API Orchestrator — 1,554 tools, 96 services. One install.

View all MCP Connectors

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/braindaamage/firefly-iii-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

firefly-iii-mcp

Features

Requirements

Installation

Configuration

Usage

Claude Desktop — stdio transport

Claude Desktop — remote HTTP transport

Claude.ai — remote HTTP transport

Docker — HTTP transport

docker-compose — Local development stack

Tool Profiles

The 7 presets

The 15 categories

Composition

Claude Desktop example

Tools Reference

Accounts (6 tools)

Transactions (7 tools)

Categories (6 tools)

Tags (6 tools)

Rules & Rule Groups (15 tools)

Budgets & Budget Limits (10 tools)

Piggy Banks (6 tools)

Bills (7 tools)

Recurrences (6 tools)

Currencies & Exchange Rates (12 tools)

Search & Autocomplete (11 tools)

Reports & Charts (15 tools)

Attachments (7 tools)

Development

License

Maintenance

Resources

Looking for Admin?

Related MCP Servers

Firefly III MCP Server

Firefly III MCP Server

Universal Firefly III AI

firefly-iii-mcp-server

Related MCP Connectors

Latest Blog Posts

MCP directory API