Firefly III MCP server deployed as a Cloudflare Worker
Firefly III MCP Server - Cloudflare Worker
This package provides an implementation of the Firefly III MCP (Model Context Protocol) server on Cloudflare Workers. With Cloudflare Workers, you can easily deploy the MCP server to the cloud and benefit from the performance advantages of a global edge network.
Features
- Global edge deployment based on Cloudflare Workers
- Low latency and high availability service
- No server maintenance required
- Seamless integration with Firefly III API
- Tool filtering support via presets or custom tags
Deployment Methods
One-Click Deployment
The simplest method is to use the "Deploy to Cloudflare Workers" button for one-click deployment:
Manual Deployment
Clone this repository:
git clone https://github.com/etnperlong/firefly-iii-mcp.git cd firefly-iii-mcpInstall dependencies:
npm installBuild the project:
npm run buildDeploy to Cloudflare Workers:
cd packages/cloudflare-worker npm run deploy
Configuration
After deployment, you need to configure the following environment variables in your Cloudflare Workers settings:
Required Variables
FIREFLY_III_BASE_URL: Your Firefly III instance URL (e.g.,https://firefly.yourdomain.com)FIREFLY_III_PAT: Your Firefly III Personal Access Token
Optional Variables
FIREFLY_III_PRESET: Tool preset to use (default, full, basic, budget, reporting, admin, automation)FIREFLY_III_TOOLS: Comma-separated list of tool tags to enable (overrides FIREFLY_III_PRESET if both are set)
Available Presets
default: Basic tools for everyday use (accounts, bills, categories, tags, transactions, search, summary)full: All available toolsbasic: Core financial management toolsbudget: Budget-focused toolsreporting: Reporting and analysis toolsadmin: Administration toolsautomation: Automation-related tools
Configuration Steps
- Go to your Cloudflare dashboard
- Navigate to Workers & Pages
- Select your deployed Worker
- Go to Settings > Variables
- Add the required and optional variables as secret variables
Usage
Once deployed and configured, you can access the MCP server at the following URL:
https://your-worker-name.your-account.workers.dev/mcp
You can provide this URL to MCP-compatible AI tools to enable them to interact with your Firefly III instance.
Custom Domain
If you want to use your own domain, you can configure a custom domain in the Cloudflare Workers settings. For specific steps, please refer to the Cloudflare documentation.
Technical Details
This package is built using the Hono framework and leverages the edge computing capabilities of Cloudflare Workers.
License
This project is licensed under the MIT License.
Tools (4)
manage_transactionsCreate, read, update, or delete financial transactions in Firefly III.manage_accountsRetrieve or update information about your financial accounts.manage_budgetsView and manage your budget allocations and spending limits.get_reportsGenerate financial reports and summaries for specific time periods.Environment Variables
FIREFLY_III_BASE_URLrequiredYour Firefly III instance URLFIREFLY_III_PATrequiredYour Firefly III Personal Access TokenFIREFLY_III_PRESETTool preset to use (default, full, basic, budget, reporting, admin, automation)FIREFLY_III_TOOLSComma-separated list of tool tags to enableConfiguration
{ "mcpServers": { "firefly-iii": { "command": "npx", "args": [ "-y", "@dmitos/firefly-iii-mcp" ], "env": { "FIREFLY_III_BASE_URL": "https://your-firefly-instance.com", "FIREFLY_III_PAT": "your-personal-access-token" } } } }