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.

• 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 install

Claude 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_token

Get 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:

claude

The 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 tool

You 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-iii

Then 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.

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 REST and SSE endpoints:

FIREFLY_URL=http://your-host:PORT FIREFLY_TOKEN=your_token PORT=3000 node index.js

Available endpoints:

npm test

78 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)