fireflyiii-mcp AGENTS.md

MCP server for Firefly III — Project Documentation

Project Overview

MCP server for Firefly III is a TypeScript implementation of an MCP (Model Context Protocol) server that bridges Claude Code to a running Firefly III personal finance instance. This is a greenfield, open-source project (MIT license).

Users can query their finances in natural language through Claude, getting answers about accounts, transactions, budgets, categories, bills, piggy banks, and financial insights without writing queries themselves.

Current state: 140 tools across 14 groups, full CRUD, stdio and HTTP (OAuth or PAT) transports, tool filtering via --preset/--groups/--read-only.

Architecture at a glance

MCP client (Claude Code / Desktop / ...)
        │
        │  stdio                          HTTP (StreamableHTTP, stateless)
        ▼                                 ▼
  StdioServerTransport          OAuth proxy (src/http.ts)
        │                         · /.well-known metadata, /oauth/{authorize,token,register,callback}
        │                           (404 instead, if FIREFLY_OAUTH_CLIENT_ID is unset — PAT-only mode)
        │                         · substitutes redirect_uri, Bearer guard
        │                         · per-request token via AsyncLocalStorage
        └────────────┬────────────┘
                     ▼
            McpServer (src/server.ts)
                     │  registerAllTools (src/tools/index.ts)
                     │  · TOOL_GROUPS / PRESETS filtering, read-only proxy
                     ▼
      Tool groups (src/tools/*.ts, 14 groups / 140 tools)
        · defineTool wrapper: zod validation, error formatting (src/tools/_helpers.ts)
        · autocomplete prompts with per-user TTL cache
                     │
                     ▼
        FireflyClient (src/client.ts)
        · Bearer auth, 30s timeout, FireflyError → friendly messages
                     │
                     ▼
        Transform layer (src/transform.ts)
        · unwraps JSON:API envelopes → flat objects + pagination
                     │
                     ▼
            Firefly III REST API (/api/v1)