Firefly III MCP Server

Предоставьте ИИ-ассистенту доступ на чтение — и, если разрешите, на запись — к вашему собственному экземпляру Firefly III через Model Context Protocol.

146 операций по 26 сущностям: транзакции, счета, бюджеты, категории, теги, счета-фактуры, копилки, правила, а также поиск и анализ периодов.

Türkçe: README.tr.md

Каждый запускает это против своего экземпляра Firefly со своим токеном. Ничего не передаётся, и никакие данные не проходят через третьи стороны.

Install

Требуется Node.js 20.6+. Самый быстрый способ — позволить установщику сделать всё самому:

npx -y @yakupemreyerli/firefly-mcp setup

Он запрашивает адрес вашего Firefly III и API-токен, проверяет, что они действительно работают с вашим экземпляром, а затем настраивает Claude Code и Claude Desktop, если находит их — создавая резервные копии всего, к чему прикасается, и не трогая ваши остальные MCP-серверы. Для любого другого клиента он выводит конфигурацию для вставки.

Если вы предпочитаете сделать это вручную:

Claude Code

claude mcp add firefly \
  --env FIREFLY_API_URL=your-firefly.example \
  --env FIREFLY_API_TOKEN=your-token \
  -- npx -y @yakupemreyerli/firefly-mcp

Claude Desktop, Cursor и другие клиенты

Добавьте это в файл конфигурации MCP клиента:

{
  "mcpServers": {
    "firefly": {
      "command": "npx",
      "args": ["-y", "@yakupemreyerli/firefly-mcp"],
      "env": {
        "FIREFLY_API_URL": "your-firefly.example",
        "FIREFLY_API_TOKEN": "your-token"
      }
    }
  }
}

Получите токен в Firefly III → Options → Profile → OAuth → Create New Personal Access Token. Для URL достаточно вашего домена — https:// и /api/v1 подставляются автоматически. Укажите полный URL, если ваш экземпляр находится в подкаталоге, на нестандартном порту или по обычному http.

Related MCP server: Firefly III MCP Server

Насколько далеко это может зайти

Через stdio — настолько, насколько позволяет токен Firefly: вы можете попросить ассистента записать покупку или категоризировать транзакцию, и он это сделает. Не существует общесерверной настройки прав — для сеанса, который может только отвечать на вопросы, выдайте в Firefly III Personal Access Token только для чтения, чтобы ограничение накладывалось Firefly, а не переменной, которую тот же человек может изменить.

Через HTTP с OAuth доступ определяется для каждого подключения: firefly:read, firefly:write и firefly:destructive выдаются на экране пароля, а поверхность, которая не была предоставлена, скрывается и отклоняется.

Что видит ассистент

Пять инструментов, а не 146 — и выполнение разделено по уровню риска, чтобы хост мог отличить чтение баланса от удаления транзакции:

Каждый несёт аннотации инструментов MCP (readOnlyHint, destructiveHint, idempotentHint), и разделение соблюдается, а не просто заявлено: удаление, запрошенное через firefly_query, отклоняется. Подключение, получившее только firefly:read, вообще не видит два пишущих инструмента.

Большинство MCP-клиентов деградируют после примерно 40 инструментов, поэтому поверхность состоит из трёх.

Ответы обрезаются перед тем, как попасть к модели: пустые и null-атрибуты всегда отбрасываются, а каждый инструмент выполнения принимает список fields, который оставляет только те атрибуты, которые вы назвали — на большом списке транзакций это сокращение примерно на 90%.

Конфигурация

Удалённый HTTP-режим

Для клиентов, которые подключаются по HTTP, а не запускают процесс — например, n8n — тот же сервер поддерживает streamable HTTP:

export MCP_HTTP_TOKEN=$(openssl rand -hex 32)
npx -y -p @yakupemreyerli/firefly-mcp firefly-mcp-http

firefly-mcp-http — это второй бинарный файл в том же пакете, поэтому npx требует -p, чтобы указать пакет и команду отдельно.

Он отказывается запускаться без MCP_HTTP_TOKEN, и каждый запрос к /mcp должен содержать Authorization: Bearer <token>. /health открыт для проверок контейнеров. В репозитории есть Dockerfile и compose.example.yml.

Поместите его за TLS. Токен — единственное, что отделяет интернет от доступа на запись к вашей финансовой истории — не открывайте порт напрямую.

Документация

Docker

Для HTTP-режима есть готовый образ для linux/amd64 и linux/arm64:

docker run -d \
  -e FIREFLY_API_URL=your-firefly.example \
  -e FIREFLY_API_TOKEN=your-token \
  -e MCP_HTTP_HOST=0.0.0.0 \
  -e MCP_HTTP_TOKEN="$(openssl rand -hex 32)" \
  -p 3000:3000 \
  ghcr.io/yakupemreyerli/mcp-firefly-iii:latest

/health отвечает без токена, для проверок контейнеров. Всё на /mcp требует Authorization: Bearer <MCP_HTTP_TOKEN>.

Для всего, от чего вы зависите, фиксируйте версию (:0.3.1), а не :latest.

Разработка

git clone https://github.com/YakupEmreYerli/mcp-firefly-iii.git
cd mcp-firefly-iii
npm install
cp .env.example .env    # fill in your instance
npm test                # mocked; never touches a live instance
npm run build
npm run check           # read-only connection check against .env

Тесты используют моки и никогда не выходят в сеть. npm run smoke:live — инструмент мейнтейнера, который проходит по всем операциям чтения против экземпляра из .env; он только для чтения и не входит в опубликованный пакет.

Участие в разработке

Баг-репорты и пул-реквесты приветствуются. Смотрите CONTRIBUTING.md: там описана структура кода, как запускать тесты и особенности Firefly III, которые стоит знать, прежде чем что-то трогать.

Нашли проблему безопасности? Пожалуйста, сообщите о ней конфиденциально — см. SECURITY.md.

Лицензия

MIT — см. LICENSE.