个人财务管理服务器

"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"

# 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 .

# 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

{
  "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"
      }
    }
  }
}

{
  "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"
      }
    }
  }
}

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

# Run all tests
make test-all

# Run with coverage
make coverage

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

# Development with .env file
make dev

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