Firefly III MCP Server
About
A Model Context Protocol (MCP) server for Firefly III, a free and open-source personal finance manager. It allows AI tools to programmatically manage Firefly III accounts and transactions, enabling the creation of AI assistants for personal finance and accounting.
Details
- License
- MIT
Explore
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
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
Firefly III MCP ServerCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
A running Firefly III instance
A Cloudflare account if you plan to deploy using the "Deploy to Cloudflare" button
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:
Set the following environment variables before running the server:
``bash
FIREFLY_III_BASE_URL="YOUR_FIREFLY_III_INSTANCE_URL" # e.g., https://firefly.yourdomain.com
FIREFLY_III_PAT="YOUR_FIREFLY_III_PAT"
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: or FIREFLY_III_TOOLS`
FIREFLY_III_PRESET="default" # Available: default, full, basic, budget, reporting, admin, automation
FIREFLY_III_TOOLS="accounts,transactions,categories"
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"
]
}
}
}
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
You can filter which tools are exposed to the MCP client to reduce token usage and focus on specific functionality:
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"firefly iii mcp server": {
"firefly-iii": {
"command": "npx",
"args": [
"@firefly-iii-mcp/local"
],
"env": {
"FIREFLY_III_BASE_URL": "<YOUR_FIREFLY_III_BASE_URL>",
"FIREFLY_III_PAT": "<YOUR_FIREFLY_III_PAT>"
}
}
}
}
}McpServers
{
"firefly-iii": {
"command": "npx",
"args": [
"@firefly-iii-mcp/local"
],
"env": {
"FIREFLY_III_BASE_URL": "<YOUR_FIREFLY_III_BASE_URL>",
"FIREFLY_III_PAT": "<YOUR_FIREFLY_III_PAT>"
}
}
}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:
```bash
FIREFLY_III_BASE_URL="YOUR_FIREFLY_III_INSTANCE_URL" # e.g., https://firefly.yourdomain.com
FIREFLY_III_PAT="YOUR_FIREFLY_III_PAT"
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
