firefly-iii

This MCP server provides programmatic access to a Firefly III instance from MCP clients such as Claude Desktop, Cursor IDE, or other tools that support the Model Context Protocol. It exposes a range of Firefly III API capabilities through a collection of tools or direct API access, depending on configuration. You can enable a focused set of entities (accounts, transactions, budgets, categories, bills, piggy banks, and rules) or opt for a consolidated dynamic interface that lets you execute arbitrary Firefly III operations via a single meta-tool. The server emphasizes type-safe requests and responses using Pydantic models, and it supports both dynamic operation discovery and direct operation-level tools when FIREFLY_DIRECT_MODE is enabled.

To use the server, configure your MCP client to launch the server with the appropriate environment variables and then interact with the available tools. If you choose consolidated mode, you’ll call a generic execute/list/schema tools (firefly_execute, firefly_list_operations, firefly_get_schema) to browse and perform operations. If you enable direct mode, you’ll see individual tools such as account_list, account_get, transaction_create, budget_list, and more, each mapping to a specific Firefly III API endpoint. Ensure your MCP client passes the Firefly III API URL and token in the environment so the server can authenticate and communicate with Firefly III.

The documentation also covers integration with the MCP Inspector for testing and debugging, as well as local development workflows. When using the MCP Inspector, you can validate requests, inspect schemas, and verify connectivity to your Firefly III instance before using the tools in production.

Prerequisites:

• Python 3.12 or newer
• A running Firefly III instance with an API token
• Access to install Python packages (pip)

1. Clone the repository:

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

2. Create and activate a Python virtual environment:

python -m venv .venv
# macOS/Linux
source .venv/bin/activate
# Windows
.venv\Scripts\activate

3. Install the package in editable mode (UV workflow is recommended):

pip install -e .

4. Create a .env file in the project root with your Firefly III configuration (see Environment Variables Reference in the README):

FIREFLY_API_URL=https://your-firefly-instance.com/api/v1
FIREFLY_API_TOKEN=your_token_here
FIREFLY_ENABLED_ENTITIES=all  # or a comma-separated subset like account,transaction
FIREFLY_DIRECT_MODE=false   # set to true to enable direct operation tools
FIREFLY_LOG_LEVEL=INFO

5. Run the server using UV (recommended for development):

uv sync

Or run directly for development:

uv run firefly-mcp

6. Verify the server is running and accessible via your MCP client by loading the available tools and testing a simple operation, e.g., listing accounts or retrieving a transaction.

Tips and considerations:

• Ensure FIREFLY_API_URL uses your Firefly III version (v1 API is assumed) and that FIREFLY_API_TOKEN has the necessary permissions.
• If you enable FIREFLY_ENABLED_ENTITIES=all, be aware this will register many tools (potentially up to ~76); if your client has tool limits, consider keeping a limited subset and/or using FIREFLY_DIRECT_MODE=false for consolidated tools.
• In consolidated mode, use firefly_execute to perform operations dynamically, while in direct mode you’ll get explicit tools like account_list, transaction_create, etc.
• For development, MCP Inspector can help you validate schemas and test operations against your Firefly III instance.
• If SSL verification needs to be disabled during development, you can set FIREFLY_DISABLE_SSL_VERIFY=true (not recommended for production).
• Keep your API token secure; don’t commit it to version control. Use environment variables or secret management in your deployment environment.