Content
# 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.
*[查看中文版](README_ZH.md)*
## 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](https://www.firefly-iii.org/) 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](https://docs.firefly-iii.org/how-to/firefly-iii/features/api/).
### 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"
# 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](https://claude.ai/download).
Basic run command:
```bash
npx @firefly-iii-mcp/local --pat YOUR_PAT --baseUrl YOUR_FIREFLY_III_URL
```
You can also filter the available tools to reduce token usage:
```bash
# 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](https://modelcontextprotocol.io/quickstart/user) for configuration in JSON format.
```json
{
"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
```bash
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
```bash
npm install @firefly-iii-mcp/server
```
Basic usage:
```typescript
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](packages/server/README.md).
### Method 3: Deploy to Cloudflare Workers (Recommended for Production)
You can easily deploy this MCP server to Cloudflare Workers using the button below:
[](https://deploy.workers.cloudflare.com/?url=https://github.com/etnperlong/firefly-iii-mcp/tree/main/packages/cloudflare-worker)
**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:
```bash
git clone https://github.com/etnperlong/firefly-iii-mcp.git
cd firefly-iii-mcp
```
2. Install dependencies:
```bash
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:
```bash
npm run build
```
5. Start the development server:
```bash
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](https://turbo.build/) to manage the monorepo workflow and [Changesets](https://github.com/changesets/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](CONTRIBUTING.md).
## Acknowledgements
This project utilizes and modifies generation scripts from [harsha-iiiv/openapi-mcp-generator](https://github.com/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](CONTRIBUTING.md) for detailed guidelines on how to contribute.
## License
This project is licensed under the [MIT License](LICENSE).
