# Firefly III MCP Server

A Model Context Protocol (MCP) server that provides programmatic access to [Firefly III](https://www.firefly-iii.org/) personal finance management through Claude Desktop, Cursor IDE, and other MCP-compatible AI assistants.

## 📚 Documentation

**📖 [Full Documentation](https://horsfallnathan.github.io/firefly-iii-mcp-server/)**

## Overview

This MCP server enables AI assistants to interact with your Firefly III instance, allowing you to manage your personal finances through natural language conversations. You can:

- **💰 Manage accounts**: List, create, update, and delete asset, expense, revenue, and liability accounts
- **📊 Handle transactions**: Create, retrieve, update, and delete financial transactions
- **💳 Budget management**: Work with budgets, budget limits, and track spending
- **🏷️ Categorization**: Manage transaction categories and tags
- **💸 Bill tracking**: Handle recurring bills and payment monitoring
- **🐷 Piggy banks**: Manage savings goals and track progress
- **⚙️ Rules & automation**: Configure transaction rules and rule groups

## Key Features

- **🤖 AI Integration**: Works seamlessly with Claude Desktop, Cursor IDE, and other MCP clients
- **💡 Comprehensive API**: Supports most Firefly III v1 API endpoints
- **⚡ Flexible modes**: Choose between consolidated tools or direct API access
- **🔒 Type-safe**: Full Pydantic model validation for all requests/responses
- **🎯 Configurable**: Enable only the Firefly III entities you need

## Quick Example

Once set up, you can interact with your finances naturally:

```
"Show me my account balances"
"Create a new expense for $25.50 at Coffee Shop from my Checking Account"
"What's my budget status for this month?"
"List all my transactions from last week"
"Create a new savings goal for a vacation with a target of $2000"
"Show me all bills that are due this month"
"Help me create a transaction rule that automatically categorizes Starbucks purchases as 'Coffee'"
"Create a new budget category for 'Home Improvement' with a $500 monthly limit"
```

## Requirements

- Python 3.12+
- A running Firefly III instance
- Firefly III API token (Personal Access Token)

## 🚀 Quick Setup

### Local Installation

Clone and set up the project locally:

```bash
# Clone the repository
git clone https://github.com/horsfallnathan/firefly-iii-mcp-server.git firefly-mcp
cd firefly-mcp

# Install with UV (recommended)
uv sync

# Or with pip
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e .
```

### Configuration

Create a `.env` file in the project root:

```bash
# Required: Your Firefly III API URL and token
FIREFLY_API_URL=https://your-firefly-instance.com/api/v1
FIREFLY_API_TOKEN=your_token_here

# Optional: Enable all entities (default: just accounts). Requires `FIREFLY_DIRECT_MODE=true`
# Enabling all entities would lead to about 76 tools being registered and most clients suggest a maximum of 40 tools
FIREFLY_ENABLED_ENTITIES=all

# When false, the server will register consolidated tools for dynamic operation. When true, it will register individual tools for each operation
FIREFLY_DIRECT_MODE=false

FIREFLY_LOG_LEVEL=INFO
```

**🔑 Getting a Firefly III API Token:**
1. Log into your Firefly III instance
2. Go to **Options** → **Profile** → **OAuth**
3. Click **Create New Token**
4. Give it a descriptive name (e.g., "MCP Server")
5. Copy the generated token to your `.env` file

**📖 [See full configuration guide](https://horsfallnathan.github.io/firefly-iii-mcp-server/configuration/)**

## 🔌 MCP Client Integration

### Cursor IDE

Add to your workspace or global settings:

```json
{
  "mcp.servers": {
    "firefly-mcp": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/firefly-mcp", "run", "firefly-mcp"],
      "env": {
        "FIREFLY_API_URL": "https://your-firefly-instance.com/api/v1",
        "FIREFLY_API_TOKEN": "your_token_here",
        "FIREFLY_ENABLED_ENTITIES": "all",
        "FIREFLY_DIRECT_MODE": "false"
      }
    }
  }
}
```

### VSCode

Create an `mcp.json` file in your project root or workspace:

```json
{
  "servers": {
    "firefly-mcp": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/firefly-mcp", "run", "firefly-mcp"],
      "env": {
        "FIREFLY_API_URL": "https://your-firefly-instance.com/api/v1",
        "FIREFLY_API_TOKEN": "your_token_here",
        "FIREFLY_ENABLED_ENTITIES": "all",
        "FIREFLY_DIRECT_MODE": "false"
      }
    }
  }
}
```
## Operation Modes

### Consolidated Mode (Default)
Provides three meta-tools for dynamic operation:
- `firefly_execute(entity, operation, params)` - Execute any Firefly III operation
- `firefly_list_operations(entity?)` - List available operations  
- `firefly_get_schema(entity, operation)` - Get parameter schema for operations

### Direct Mode
Set `FIREFLY_DIRECT_MODE=true` to register individual tools for each operation:
- `account_list(limit?, page?)` - List accounts
- `account_get(id)` - Get account details
- `transaction_create(transactions)` - Create transactions
- And many more...

## 🛠️ Development & Testing

### Using MCP Inspector

For development and debugging, use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector):

```bash
# Install and run MCP Inspector
npx @modelcontextprotocol/inspector uv run firefly-mcp
```

The MCP Inspector provides a web interface where you can:
- 🧪 Test all available tools and operations
- 🔍 Inspect request/response schemas  
- 🐛 Debug server connectivity and authentication
- ✅ Validate your Firefly III configuration

**📖 [See full development guide](https://horsfallnathan.github.io/firefly-iii-mcp-server/development/mcp-inspector/)**

### Running Tests

```bash
# Run all tests
make test-all

# Run with coverage
make coverage

# Run specific test types
make test-unit
make test-integration
```

### Local Development

```bash
# Development with .env file
make dev

# Direct execution
uv run firefly-mcp
python -m firefly_mcp.main
```

## 📋 Environment Variables Reference

| Variable | Default | Description |
|----------|---------|-------------|
| `FIREFLY_API_URL` | `https://firefly.dev.nlocal/api/v1` | Your Firefly III API base URL |
| `FIREFLY_API_TOKEN` | *(required)* | Personal Access Token from Firefly III |
| `FIREFLY_DISABLE_SSL_VERIFY` | `false` | Disable SSL verification for development |
| `FIREFLY_DIRECT_MODE` | `false` | Enable individual tools for each operation |
| `FIREFLY_ENABLED_ENTITIES` | `account` | Comma-separated list of entities to enable |
| `FIREFLY_LOG_LEVEL` | `INFO` | Logging level (DEBUG, INFO, WARNING, ERROR) |


## 🎯 API Compatibility

This MCP server is compatible with Firefly III API v1. It has been tested with:
- ✅ Firefly III v6.x

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run the test suite
6. Submit a pull request

## 📄 License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). See the [LICENSE](LICENSE) file for details.