Firefly III MCP Server

This is a Model Context Protocol (MCP) server for Firefly III, a free and open-source personal finance manager. Through this MCP server, users can leverage AI tools to manage their Firefly III accounts and transactions, creating AI assistants for personal finance and accounting.

查看中文版

Project Structure

This project uses a Turborepo-managed monorepo structure, containing the following main packages:

• @firefly-iii-mcp/core - Core functionality module providing the foundation for interacting with the Firefly III API
• @firefly-iii-mcp/local - Command-line tool for running the MCP server locally
• @firefly-iii-mcp/cloudflare-worker - Implementation for deployment to Cloudflare Workers
• @firefly-iii-mcp/server - Express-based server implementation with Streamable HTTP and SSE support

Features

• Interact with Firefly III instances via AI
• Programmatically manage accounts and transactions
• Extensible toolset for various financial operations
• Support for both local and cloud deployment
• Compatible with the Model Context Protocol standard
• Tool filtering via presets or custom tags to reduce token usage

Prerequisites

• A running Firefly III instance
• A Cloudflare account if you plan to deploy using the "Deploy to Cloudflare" button

Getting Started

1. Obtain a Firefly III Personal Access Token (PAT)

To allow the MCP server to interact with your Firefly III instance, you need to generate a Personal Access Token (PAT):

1. Log in to your Firefly III instance
2. Navigate to Options > Profile > OAuth
3. Under the "Personal access tokens" section, click on "Create new token"
4. Give your token a descriptive name (e.g., "MCP Server Token")
5. Click "Create"
6. Important: Copy the generated token immediately. You will not be able to see it again.

For more details, refer to the official Firefly III documentation on Personal Access Tokens.

2. Configure the MCP Server

You need to provide the Firefly III PAT and your Firefly III instance URL to the MCP server. This can be done in several ways:

Request Headers (Recommended)

Provide these values in the headers of each request to the MCP server. This is generally the most secure method:

• X-Firefly-III-Url: Your Firefly III instance URL (e.g., https://firefly.yourdomain.com)
• Authorization: The Personal Access Token, typically prefixed with Bearer (e.g., Bearer YOUR_FIREFLY_III_PAT)

Please consult the documentation of the AI tool or client you are using for the exact header names it expects.

Query Parameters (Use with caution)

Alternatively, you can provide these values in the query parameters of each request to the MCP server:

• baseUrl: Your Firefly III instance URL
• pat: Your Firefly III Personal Access Token

Please note that URLs, including query parameters, can be logged in various places, potentially exposing sensitive information.

Environment Variables (Primarily for self-hosting/local development)

Set the following environment variables before running the server:

FIREFLY_III_BASE_URL="YOUR_FIREFLY_III_INSTANCE_URL" # e.g., https://firefly.yourdomain.com
FIREFLY_III_PAT="YOUR_FIREFLY_III_PAT"
# Optional: Filter tools using preset or custom tags
FIREFLY_III_PRESET="default" # Available: default, full, basic, budget, reporting, admin, automation
# Or specify custom tool tags (overrides preset if both are set)
FIREFLY_III_TOOLS="accounts,transactions,categories"

Running the MCP Server

Method 1: Local Mode

This method is suitable for clients that support calling MCP tools via standard input/output (stdio), such as Claude Desktop.

Basic run command:

npx @firefly-iii-mcp/local --pat YOUR_PAT --baseUrl YOUR_FIREFLY_III_URL

You can also filter the available tools to reduce token usage:

# Using a preset
npx @firefly-iii-mcp/local --pat YOUR_PAT --baseUrl YOUR_FIREFLY_III_URL --preset budget

# Using custom tool tags
npx @firefly-iii-mcp/local --pat YOUR_PAT --baseUrl YOUR_FIREFLY_III_URL --tools accounts,transactions,categories

You can also refer to the official tutorial for configuration in JSON format.

{
  "mcpServers": {
    "firefly-iii": {
      "command": "npx",
      "args": [
        "@firefly-iii-mcp/local",
        "--pat",
        "<Your Firefly III Personal Access Token>",
        "--baseUrl",
        "<Your Firefly III Base URL>",
        "--preset",
        "default"
      ]
    }
  }
}

Method 2: Express Server (Recommended for Web Apps)

This method provides an HTTP-based server with Streamable HTTP and SSE support, making it ideal for web applications.

As a Command-Line Tool

npx @firefly-iii-mcp/server --pat YOUR_PAT --baseUrl YOUR_FIREFLY_III_URL

Command-line options:

• -p, --pat <token> - Firefly III Personal Access Token
• -b, --baseUrl <url> - Firefly III Base URL
• -P, --port <number> - Port to listen on (default: 3000)
• -l, --logLevel <level> - Log level: debug, info, warn, error (default: info)
• -s, --preset <name> - Tool preset to use (default, full, basic, budget, reporting, admin, automation)
• -t, --tools <list> - Comma-separated list of tool tags to enable

As a Library

npm install @firefly-iii-mcp/server

Basic usage:

import { createServer } from '@firefly-iii-mcp/server';

const server = createServer({
  port: 3000,
  pat: process.env.FIREFLY_III_PAT,
  baseUrl: process.env.FIREFLY_III_BASE_URL,
  enableToolTags: ['accounts', 'transactions', 'categories'] // Optional: Filter available tools
});

server.start().then(() => {
  console.log('MCP Server is running on http://localhost:3000');
});

For more details, see the @firefly-iii-mcp/server documentation.

Method 3: Deploy to Cloudflare Workers (Recommended for Production)

You can easily deploy this MCP server to Cloudflare Workers using the button below:

Note: After deploying, you will need to configure the environment variables in your Cloudflare Worker's settings:

1. Go to your Cloudflare dashboard
2. Navigate to Workers & Pages
3. Select your deployed Worker
4. Go to Settings > Variables
5. Add the following variables:
   • Required: FIREFLY_III_BASE_URL and FIREFLY_III_PAT
   • Optional: FIREFLY_III_PRESET or FIREFLY_III_TOOLS

Method 4: Run Locally from Source

[!NOTE] For production use, it is recommended to use the NPM package or deploy to Cloudflare Workers.

1. Clone the repository:

   git clone https://github.com/etnperlong/firefly-iii-mcp.git
   cd firefly-iii-mcp

2. Install dependencies:

   npm install

3. Create a .env file:

   FIREFLY_III_BASE_URL="YOUR_FIREFLY_III_INSTANCE_URL"
   FIREFLY_III_PAT="YOUR_FIREFLY_III_PAT"
   # Optional: Filter tools
   FIREFLY_III_PRESET="default"
   # Or
   FIREFLY_III_TOOLS="accounts,transactions,categories"
   

4. Build the project:

   npm run build

5. Start the development server:

   npm run dev

Tool Filtering Options

You can filter which tools are exposed to the MCP client to reduce token usage and focus on specific functionality:

Available Presets

• default: Basic tools for everyday use (accounts, bills, categories, tags, transactions, search, summary)
• full: All available tools
• basic: Core financial management tools
• budget: Budget-focused tools
• reporting: Reporting and analysis tools
• admin: Administration tools
• automation: Automation-related tools

Development Guide

This project uses Turborepo to manage the monorepo workflow and Changesets for versioning and publishing.

Common Commands

• Build all packages: npm run build
• Build specific packages: npm run build:core or npm run build:local
• Clean build artifacts: npm run clean
• Development mode: npm run dev
• Publish packages: npm run publish-packages

For detailed development guidelines, please refer to the contribution guide.

Acknowledgements

This project utilizes and modifies generation scripts from harsha-iiiv/openapi-mcp-generator. Many thanks to the original authors for their work.

Contributing

Contributions are welcome! This project uses Turborepo to manage the monorepo workflow. Please see CONTRIBUTING.md for detailed guidelines on how to contribute.

License

This project is licensed under the MIT License.