Firefly Iii MCP server

Firefly III MCP Server

A Model Context Protocol server that gives an AI assistant access to your own Firefly III instance — 152 operations behind 5 scoped tools, with reading, writing and deleting kept as three separate, explicitly-authorized surfaces instead of one tool that can do all three.

Türkçe: README.tr.md

• "What did I spend the most on last month?"
• "Find uncategorised transactions from August and suggest categories."
• "Show me subscriptions whose amount went up."

Everyone runs this against their own Firefly instance with their own token — there is no hosted backend or relay in between.

Listed in the official MCP Registry as io.github.YakupEmreYerli/mcp-firefly-iii, on Glama, and in Firefly III's own third-party apps documentation. Every release is built and published by CI from a tagged commit, with npm provenance attesting that the tarball came from this repository.

Demo

https://github.com/user-attachments/assets/4866f13e-ff09-43b0-b99c-2b4789a30224

38-second demo: ask a financial question, read the answer through MCP, preview a change with dry_run, approve it, and write it back to Firefly III. Recorded against a synthetic instance — all financial data shown is fabricated.

Features

• 5 meta-tools, not 152. fireflyquery, fireflymutate, fireflydestructive, plus fireflylistoperations and fireflyget_schema for discovery — a typed registry maps every Firefly endpoint onto these instead of flooding the model's tool list.
• dryrun on every write**, returning the exact request — resolved record IDs included — without sending it.
• Bulk writes can't run blind. Filter-driven updates require max_matches and refuse an incomplete scan before the first write; multi-split transaction groups are rejected outright rather than risk folding their amounts together.
• Read/write/destructive are separately scoped and enforced, not just annotated — over stdio by the Firefly token, over HTTP by OAuth scope or a static token.
• Embedded OAuth 2.1 authorization server for Claude web, Claude mobile, and ChatGPT — no separate Keycloak or Authentik install.
• Docker images for linux/amd64/linux/arm64, and a self-checking documentation pipeline that keeps the tool catalogue in sync with the code.
• It tells you when it is out of date. Once a day it checks whether a newer version exists and, if so, says so once — a line on stderr, a sentence beside the next answer. MCPUPDATECHECK=false turns it off.

Prerequisites

• A running Firefly III instance and a Personal Access Token (Firefly III → Options → Profile → OAuth → Create New Personal Access Token)
• Node.js 20.6+, unless you're using Docker

Usage

Shortened. The full README is on GitHub.