mcp-server-firefly-iii: Instructions file for Claude Code

Firefly III MCP Server — Claude Code Guide

MCP server bridging Firefly III personal finance manager to AI assistants. 66 tools, Node.js, fully tested (78 tests).

---

Quick Setup (Claude Code)

1. Create .env in the repo root (gitignored — never committed):

FIREFLY_URL=http://your-host:PORT
FIREFLY_TOKEN=your_personal_access_token

Get your token: Firefly III → Profile → OAuth → Personal Access Tokens → Create new token

2. Create .mcp.json in the repo root (gitignored — never committed):

{
  "mcpServers": {
    "firefly-iii": {
      "command": "node",
      "args": ["./index.js"]
    }
  }
}

The server reads credentials from .env automatically via dotenv. No secrets in .mcp.json.

3. Start Claude Code from this directory:

claude

The server starts automatically. On first launch Claude Code asks for approval (once only). To skip the prompt, add "enabledMcpjsonServers": ["firefly-iii"] to ~/.claude/settings.json.

3. Verify the connection:

Use the get_about tool

You should receive your Firefly III version and API information. An Unauthenticated error means the token in .mcp.json is still the placeholder — update it with your real token.

---

Using from Other Projects

Copy .mcp.json with an absolute path so Claude Code can find the server from any directory:

{
  "mcpServers": {
    "firefly-iii": {
      "command": "node",
      "args": ["C:/absolute/path/to/mcp-server-firefly-iii/index.js"],
      "env": {
        "FIREFLY_URL": "http://your-host:PORT",
        "FIREFLY_TOKEN": "your_personal_access_token"
      }
    }
  }
}

---

Claude Desktop Setup

Config file locations:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "firefly-iii": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server-firefly-iii/index.js"],
      "env": {
        "FIREFLY_URL": "http://your-host:PORT",
        "FIREFLY_TOKEN": "your_personal_access_token"
      }
    }
  }
}