Firefly III MCP Server

Это сервер Model Context Protocol (MCP) для Firefly III — бесплатного менеджера личных финансов с открытым исходным кодом. Благодаря этому MCP-серверу пользователи могут использовать AI-инструменты для управления своими счетами и транзакциями Firefly III, создавая AI-ассистентов для личных финансов и учёта.

Посмотреть китайскую версию

Структура проекта

Проект использует монорепозиторий, управляемый Turborepo, и содержит следующие основные пакеты:

• @firefly-iii-mcp/core — модуль базовой функциональности, обеспечивающий основу для взаимодействия с Firefly III API

• @firefly-iii-mcp/local — инструмент командной строки для локального запуска MCP-сервера

• @firefly-iii-mcp/cloudflare-worker — реализация для развертывания в Cloudflare Workers

• @firefly-iii-mcp/server — сервер на базе Express с поддержкой Streamable HTTP и SSE

Related MCP server: Firefly III MCP Server

Возможности

• Взаимодействие с экземплярами Firefly III через AI

• Программное управление счетами и транзакциями

• Расширяемый набор инструментов для различных финансовых операций

• Поддержка локального и облачного развертывания

• Совместимость со стандартом Model Context Protocol

• Фильтрация инструментов с помощью пресетов или пользовательских тегов для снижения расхода токенов

Предварительные требования

• Работающий экземпляр Firefly III

• Учетная запись Cloudflare, если вы планируете развертывание с помощью кнопки «Deploy to Cloudflare»

Начало работы

1. Получение Personal Access Token (PAT) Firefly III

Чтобы MCP-сервер мог взаимодействовать с вашим экземпляром Firefly III, необходимо создать Personal Access Token (PAT):

1. Войдите в свой экземпляр Firefly III.

2. Перейдите в раздел Options > Profile > OAuth.

3. В разделе «Personal access tokens» нажмите «Create new token».

4. Дайте токену описательное имя (например, «MCP Server Token»).

5. Нажмите «Create».

6. Важно: немедленно скопируйте созданный токен. Вы не сможете увидеть его снова.

Подробнее см. в официальной документации Firefly III: Personal Access Tokens.

2. Настройка MCP-сервера

Необходимо передать MCP-серверу PAT Firefly III и адрес вашего экземпляра Firefly III. Это можно сделать несколькими способами.

Заголовки запросов (рекомендуется)

Передавайте эти значения в заголовках каждого запроса к MCP-серверу. Обычно это самый безопасный способ:

• X-Firefly-III-Url: URL вашего экземпляра Firefly III (например, https://firefly.yourdomain.com)

• Authorization: Personal Access Token, как правило, с префиксом Bearer (например, Bearer YOUR_FIREFLY_III_PAT)

Уточняйте точные названия заголовков в документации используемого вами AI-инструмента или клиента.

Параметры запроса (используйте с осторожностью)

Кроме того, вы можете передавать эти значения в параметрах запроса к MCP-серверу:

• baseUrl: URL вашего экземпляра Firefly III

• pat: ваш Personal Access Token Firefly III

Обратите внимание: URL-адреса, включая параметры запроса, могут записываться в журналы в разных системах, что может привести к раскрытию чувствительных данных.

Переменные окружения (в основном для самостоятельного хостинга и локальной разработки)

Укажите следующие переменные окружения перед запуском сервера:

FIREFLY_III_BASE_URL="YOUR_FIREFLY_III_INSTANCE_URL" # e.g., https://firefly.yourdomain.com
FIREFLY_III_PAT="YOUR_FIREFLY_III_PAT"
# Optional: Filter tools using preset or custom tags
FIREFLY_III_PRESET="default" # Available: default, full, basic, budget, reporting, admin, automation
# Or specify custom tool tags (overrides preset if both are set)
FIREFLY_III_TOOLS="accounts,transactions,categories"

Running MCP-сервера

Способ 1: Локальный режим

Этот способ подходит для клиентов, поддерживающих вызов MCP-инструментов через стандартный ввод/вывод (stdio), например Claude Desktop.

Базовая команда запуска:

npx @firefly-iii-mcp/local --pat YOUR_PAT --baseUrl YOUR_FIREFLY_III_URL

Вы также можете отфильтровать доступные инструменты, чтобы снизить расход токенов:

# Using a preset
npx @firefly-iii-mcp/local --pat YOUR_PAT --baseUrl YOUR_FIREFLY_III_URL --preset budget

# Using custom tool tags
npx @firefly-iii-mcp/local --pat YOUR_PAT --baseUrl YOUR_FIREFLY_III_URL --tools accounts,transactions,categories

Кроме того, настройку по JSON можно выполнить по официальной инструкции.

{
  "mcpServers": {
    "firefly-iii": {
      "command": "npx",
      "args": [
        "@firefly-iii-mcp/local",
        "--pat",
        "<Your Firefly III Personal Access Token>",
        "--baseUrl",
        "<Your Firefly III Base URL>",
        "--preset",
        "default"
      ]
    }
  }
}

Способ 2: Express-сервер (рекомендуется для веб-приложений)

Этот способ предоставляет HTTP-сервер с поддержкой Streamable HTTP и SSE, что делает его идеальным для веб-приложений.

Как инструмент командной строки

npx @firefly-iii-mcp/server --pat YOUR_PAT --baseUrl YOUR_FIREFLY_III_URL

Параметры командной строки:

• -p, --pat <pat> — ваша Personal Access Token Firefly III

• -b, --baseUrl <url> — базовый URL Firefly III

• -P, --port <port> — порт прослушивания (по умолчанию: 3000)

• -l, --logLevel <level> — уровень логирования: debug, info, warn, error (по умолчанию: info)

• -s, --preset <name> — используемый пресет инструментов (default, full, basic, budget, reporting, admin, automation)

• -t, --tools <list> — разделённый запятыми список тегов инструментов для включения

Как библиотеки

npm install @firefly-iii-mcp/server

Базовый вариант использования:

import { createServer } from '@firefly-iii-mcp/server';

const server = createServer({
  port: 3000,
  pat: process.env.FIREFLY_III_PAT,
  baseUrl: process.env.FIREFLY_III_BASE_URL,
  enableToolTags: ['accounts', 'transactions', 'categories'] // Optional: Filter available tools
});

server.start().then(() => {
  console.log('MCP Server is running on http://localhost:3000');
});

Подробнее см. документацию @firefly-iii-mcp/server.

Способ 3: Развертывание в Cloudflare Workers (рекомендуется для продакшена)

Развернуть MCP-сервер в Cloudflare Workers можно с помощью кнопки ниже:

Примечание: После развертывания необходимо настроить переменные окружения в вашем Cloudflare Worker:

1. Перейдите на панель управления Cloudflare.

2. Откройте раздел Workers & Pages.

3. Выберите ваш развернутый Worker.

4. Перейдите в Settings > Variables.

5. Добавьте следующие переменные:

   • Обязательные: FIREFLY_III_BASE_URL и FIREFLY_III_PAT

   • Необязательные: FIREFLY_III_PRESET или FIREFLY_III_TOOLS

Способ 4: Локальный запуск из исходного кода

[!NOTE]
Для продакшн-использования рекомендуется использовать NPM-пакет или развертывание в Cloudflare Workers.

1. Клонируйте репозиторий:

   git clone https://github.com/etnperlong/firefly-iii-mcp.git
   cd firefly-iii-mcp

2. Установите зависимости:

   npm install

3. Создайте файл .env:

   FIREFLY_III_BASE_URL="YOUR_FIREFLY_III_INSTANCE_URL"
   FIREFLY_III_PAT="YOUR_FIREFLY_III_PAT"
   # Optional: Filter tools
   FIREFLY_III_PRESET="default"
   # Or
   FIREFLY_III_TOOLS="accounts,transactions,categories"

4. Соберите проект:

   npm run build

5. Запустите сервер разработки:

   npm run dev

Настройка фильтрации инструментов

Вы можете определять, какие инструменты будут доступны MCP-клиенту, чтобы уменьшить потребление токенов и сфокусироваться на нужных функциях.

Доступные пресеты

• default: базовые инструменты для повседневного использования (accounts, bills, categories, tags, transactions, search, summary)

• full: все доступные инструменты

• basic: базовые инструменты управления финансами

• budget: инструменты, ориентированные на бюджет

• reporting: инструменты для отчётов и анализа

• admin: инструменты администратора

• automation: инструменты автоматизации

Руководство по разработке

Проект использует Turborepo для управления монорепозиторием и Changesets для версионирования и публикации.

Распространённые команды

• Собрать все пакеты: npm run build

• Собрать отдельные пакеты: npm run build:core или npm run build:local

• Очистить артефакты сборки: npm run clean

• Режим разработки: npm run dev

• Опубликовать пакеты: npm run publish-packages

Подробные правила разработки описаны в руководстве по контрибуции.

Благодарности

Этот проект использует и дорабатывает скрипты генерации из harsha-iiiv/openapi-mcp-generator. Большое спасибо авторам продута за их работу.

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

Контрибуции приветствуются! Проект использует Turborepo для управления монорепозиторием. Подробное руководство участника см. в CONTRIBUTING.md.

Лицензия

Проект распространяется под лицензией MIT.