{
  "markdown": "# Universal Firefly III AI Bridge (v3.0.0)\n\nA professional-grade, AI-agnostic bridge providing exhaustive 100% API coverage for connecting AI assistants to your [Firefly III](https://github.com/firefly-iii/firefly-iii) personal finance instance.\n\n**66 tools** covering every major Firefly III capability: accounts, transactions, budgets, bills, recurring rules, automation, insights, attachments, currencies, and more.\n\n---\n\n## Compatibility\n\n| AI Platform | Protocol | Connection | Setup Guide |\n| :--- | :--- | :--- | :--- |\n| **Claude Code** | MCP (Native) | stdio | [CLAUDE.md](CLAUDE.md) |\n| **Claude Desktop** | MCP (Native) | stdio | [CLAUDE.md](CLAUDE.md) |\n| **Gemini CLI** | MCP Extension | stdio | [gemini.md](gemini.md) |\n| **Cursor / VS Code** | MCP | stdio or SSE | Manual setup below |\n| **ChatGPT** | OpenAPI Actions | REST / JSON | `/openapi.json` endpoint |\n| **Custom Apps** | REST API | HTTP | `/api/<tool>` endpoints |\n\n---\n\n## Installation\n\n### Prerequisites\n\n- [Node.js](https://nodejs.org/) v18 or later\n- A running [Firefly III](https://github.com/firefly-iii/firefly-iii) instance\n- A **Personal Access Token** from Firefly III  \n  *(Profile → OAuth → Personal Access Tokens → Create new token)*\n\n### Clone and install\n\n```bash\ngit clone https://github.com/fabianonetto/mcp-server-firefly-iii.git\ncd mcp-server-firefly-iii\nnpm install\n```\n\n---\n\n## Setup by Platform\n\n### Claude Code (Recommended)\n\nClaude Code uses `.mcp.json` in the project directory for MCP server configuration. Credentials go in a separate `.env` file so no secrets are ever in config files.\n\n**1. Create `.env`** in the repo root (gitignored — never committed):\n\n```env\nFIREFLY_URL=http://your-host:PORT\nFIREFLY_TOKEN=your_personal_access_token\n```\n\nGet your token: Firefly III → **Profile → OAuth → Personal Access Tokens → Create new token**\n\n**2. Create `.mcp.json`** in the repo root (gitignored — never committed):\n\n```json\n{\n  \"mcpServers\": {\n    \"firefly-iii\": {\n      \"command\": \"node\",\n      \"args\": [\"./index.js\"]\n    }\n  }\n}\n```\n\nThe server reads credentials from `.env` automatically. No secrets in `.mcp.json`.\n\n**3. Start Claude Code** from the repo directory:\n\n```bash\nclaude\n```\n\nThe server starts automatically. Claude Code will prompt you to approve it on first launch (once only).\n\n**4. Verify** the connection by asking:\n\n```\nUse the get_about tool\n```\n\nYou should receive your Firefly III version and API information.\n\n**Using from other projects:**  \nCopy both `.env` and `.mcp.json` to any other project directory, changing `./index.js` to the absolute path:\n\n```json\n\"args\": [\"/absolute/path/to/mcp-server-firefly-iii/index.js\"]\n```\n\nSee [CLAUDE.md](CLAUDE.md) for the full guide including auto-approval configuration.\n\n---\n\n### Claude Desktop\n\nAdd the server to your Claude Desktop config file:\n\n- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"firefly-iii\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/mcp-server-firefly-iii/index.js\"],\n      \"env\": {\n        \"FIREFLY_URL\": \"http://your-host:PORT\",\n        \"FIREFLY_TOKEN\": \"your_personal_access_token\"\n      }\n    }\n  }\n}\n```\n\nRestart Claude Desktop after saving.\n\n---\n\n### Gemini CLI Extension (One-command install)\n\n```bash\ngemini extensions install https://github.com/fabianonetto/mcp-server-firefly-iii\n```\n\nThen configure your instance:\n\n```bash\ngemini config set extensions.firefly-iii-universal-bridge.settings.FIREFLY_URL \"http://your-host:PORT\"\ngemini config set extensions.firefly-iii-universal-bridge.settings.FIREFLY_TOKEN \"your_token\"\n```\n\nSee [gemini.md](gemini.md) for the full guide.\n\n---\n\n### Docker (Official Image)\n\nThe official image is available on GitHub Packages: `ghcr.io/fabianonetto/mcp-server-firefly-iii`.\n\n#### Run as a service (SSE Mode)\nIdeal for ChatGPT Actions, Cursor (SSE), or custom integrations.\n\n```bash\ndocker run -d \\\n  --name firefly-mcp \\\n  -p 3001:3001 \\\n  -e FIREFLY_URL=\"http://your-firefly-instance\" \\\n  -e FIREFLY_TOKEN=\"your_personal_access_token\" \\\n  -e PORT=3001 \\\n  ghcr.io/fabianonetto/mcp-server-firefly-iii:latest\n```\n\n#### Run with Claude Desktop (stdio Mode)\nAdd this to your `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"firefly-iii\": {\n      \"command\": \"docker\",\n      \"args\": [\n        \"run\",\n        \"-i\",\n        \"--rm\",\n        \"-e\", \"FIREFLY_URL=http://your-host:PORT\",\n        \"-e\", \"FIREFLY_TOKEN=your_token\",\n        \"ghcr.io/fabianonetto/mcp-server-firefly-iii:latest\"\n      ]\n    }\n  }\n}\n```\n\n---\n\n### Cursor / VS Code (MCP Extension)\n\nAdd to your MCP config (`.cursor/mcp.json` or equivalent):\n\n```json\n{\n  \"mcpServers\": {\n    \"firefly-iii\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/mcp-server-firefly-iii/index.js\"],\n      \"env\": {\n        \"FIREFLY_URL\": \"http://your-host:PORT\",\n        \"FIREFLY_TOKEN\": \"your_personal_access_token\"\n      }\n    }\n  }\n}\n```\n\n---\n\n### HTTP / SSE Mode (ChatGPT Actions, Custom Apps)\n\nStart the server with a port to enable the REST and SSE endpoints:\n\n```bash\nFIREFLY_URL=http://your-host:PORT FIREFLY_TOKEN=your_token PORT=3000 node index.js\n```\n\nAvailable endpoints:\n\n| Endpoint | Description |\n| :--- | :--- |\n| `GET /sse` | SSE transport for MCP clients |\n| `POST /messages` | MCP message handler |\n| `POST /api/<tool_name>` | Direct REST call to any tool |\n| `GET /openapi.json` | OpenAPI 3.0 spec (import into ChatGPT Actions) |\n\n---\n\n## Tool Categories\n\n| Category | Tools | Description |\n| :--- | :---: | :--- |\n| Core | 1 | System info & connectivity |\n| Accounts | 5 | Full CRUD for all account types |\n| Transactions | 7 | CRUD, split transactions, search |\n| Budgets | 8 | Budgets + monetary limits |\n| Bills & Piggy Banks | 7 | Bill tracking + savings goals |\n| Automation | 11 | Rules, rule groups, webhooks |\n| Recurring | 5 | Recurring transaction rules |\n| System | 8 | Currencies + user preferences |\n| Insights | 7 | Attachments, charts, net worth, spending |\n| Meta | 4 | Categories + tags |\n| Object Groups | 2 | Account/piggy bank organization |\n| Admin | 1 | Data export |\n| **Total** | **66** | |\n\n---\n\n## Documentation\n\n| Document | Description |\n| :--- | :--- |\n| [docs/API.md](docs/API.md) | Complete reference for all 66 tools and their input schemas |\n| [docs/PROMPTS.md](docs/PROMPTS.md) | Prompt examples for common financial tasks |\n| [docs/USE_CASES.md](docs/USE_CASES.md) | Strategic guides: tax assistant, subscription auditor, receipt manager |\n| [docs/TESTING.md](docs/TESTING.md) | Test suite documentation (78 tests, all tools covered) |\n| [CLAUDE.md](CLAUDE.md) | Claude Code & Claude Desktop setup guide |\n| [gemini.md](gemini.md) | Gemini CLI extension guide |\n\n---\n\n## Running Tests\n\n```bash\nnpm test\n```\n\n78 tests covering all 66 tools. No live Firefly III instance required — all API calls are mocked.\nSee [docs/TESTING.md](docs/TESTING.md) for details.\n\n---\n\n## Security\n\n- Use a VPN or SSH tunnel if exposing the server to the internet.\n- Keep your `FIREFLY_TOKEN` secret. Never commit `.mcp.json` or `.env` files.\n- See [SECURITY.md](SECURITY.md) for the full security policy.\n\n---\n\n## Roadmap\n\n- [x] v1.x — Initial connectivity\n- [x] v2.x — Exhaustive API coverage (CRUD & core admin)\n- [x] v3.x — Power user features (splits, insights, automation)\n- [x] v3.1.0 — Official Docker image & CI/CD\n",
  "bytes": 7401,
  "sha": "ea4388bb477145c70b9144f48bae5f675704f57ded9ee335984334405c96052b",
  "repo_slug": "fabianonetto/mcp-server-firefly-iii",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_fabianonetto_mcp_server_firefly_iii_224c64eb/readme"
}