Firefly III Server

npm version License: MIT

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.

Features

• 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

Prerequisites

• Node.js >= 18
• A running Firefly III instance
• A Personal Access Token (PAT) from your Firefly III instance

Getting Your PAT

1. Log into your Firefly III instance
2. Go to Options → Profile → OAuth
3. Under Personal Access Tokens, create a new token
4. Copy the token — you'll need it for configuration

Installation

Via npm (recommended)

npm install -g firefly-iii-mcp-server

From source

git clone https://github.com/przbadu/firefly-iii-mcp-server.git
cd firefly-iii-mcp-server
npm install
npm run build

Configuration

Claude Desktop

Edit 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 Code CLI

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-server

Or 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"
      }
    }
  }
}

Usage Examples

Once configured, just talk to Claude naturally:

Recording Transactions

"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"

Querying

"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?"

Managing Finances

"Create a monthly grocery budget of $600"

"List all my expense categories"

"Tag my last 3 restaurant transactions as 'business meals'"

Available Tools

Tool	Description
firefly_create_transaction	Create withdrawal, deposit, or transfer
firefly_list_transactions	List transactions with filters
firefly_get_transaction	Get transaction details by ID
firefly_update_transaction	Update an existing transaction
firefly_delete_transaction	Delete a transaction
firefly_search_transactions	Search with Firefly III query syntax
firefly_create_account	Create a new account
firefly_list_accounts	List accounts by type
firefly_get_account	Get account details
firefly_update_account	Update account properties
firefly_delete_account	Delete an account
firefly_list_categories	List all categories
firefly_create_category	Create a category
firefly_update_category	Update a category
firefly_delete_category	Delete a category
firefly_list_budgets	List all budgets
firefly_create_budget	Create a budget
firefly_update_budget	Update a budget
firefly_delete_budget	Delete a budget
firefly_list_tags	List all tags
firefly_create_tag	Create a tag
firefly_update_tag	Update a tag
firefly_delete_tag	Delete a tag

Development

# Watch mode with auto-reload
npm run dev

# Build for production
npm run build

# Run the built server
npm start

License

MIT