mcp-freshbooks

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

Возможности

• 53 инструмента, охватывающих полный цикл бухгалтерского учета во FreshBooks

• Интеллектуальные инструменты рабочих процессов — преобразование смет в счета, выставление счетов за неоплаченное время, поиск клиентов с просроченной задолженностью, получение полных сводок по клиентам

• 5 финансовых отчетов — отчет о прибылях и убытках, сводка по налогам, старение дебиторской задолженности, балансовый отчет, полученные платежи

• Аутентификация OAuth2 с автоматическим обновлением токенов

• Чистый вывод — краткие списки, детализированные данные

• Промышленный уровень обработки ошибок и учета ограничений частоты запросов (rate limits)

• Нулевая стоимость — использует бесплатную программу для разработчиков FreshBooks

Related MCP server: moxie-mcp

Инструменты

Быстрый старт

1. Установка

pip install mcp-freshbooks

Или из исходного кода:

git clone https://github.com/AlexlaGuardia/mcp-freshbooks.git
cd mcp-freshbooks
pip install .

2. Получение учетных данных API FreshBooks

1. Зарегистрируйтесь на freshbooks.com/pages/developer-signup

2. Создайте OAuth-приложение на портале разработчика

3. Установите URI перенаправления (redirect URI) на https://localhost:8555/callback

4. Скопируйте ваш Client ID и Client Secret

3. Настройка

export FRESHBOOKS_CLIENT_ID=your_client_id
export FRESHBOOKS_CLIENT_SECRET=your_client_secret
export FRESHBOOKS_REDIRECT_URI=https://localhost:8555/callback

4. Добавление в Claude Desktop

Добавьте в ваш claude_desktop_config.json:

{
  "mcpServers": {
    "freshbooks": {
      "command": "mcp-freshbooks",
      "env": {
        "FRESHBOOKS_CLIENT_ID": "your_client_id",
        "FRESHBOOKS_CLIENT_SECRET": "your_client_secret",
        "FRESHBOOKS_REDIRECT_URI": "https://localhost:8555/callback"
      }
    }
  }
}

5. Аутентификация

Используйте инструмент freshbooks_authenticate при первом запуске. Он предоставит URL, который нужно открыть в браузере. После авторизации токены будут сохранены в ~/.mcp-freshbooks/tokens.json и будут обновляться автоматически.

Примеры использования

Кто должен мне денег?

Use get_overdue_invoices to see all past-due clients and total outstanding

Преобразование предложения в счет:

Use convert_estimate_to_invoice to turn estimate 456 into a ready-to-send invoice

Поиск неоплаченной работы:

Use get_unbilled_time to find time entries not yet on any invoice

Проверка прибыльности:

Get the profit and loss report for Q1 2026

Учет времени:

Create a 2-hour time entry for project 789 with note "API integration work"

Архитектура

src/mcp_freshbooks/
├── server.py   # MCP server with 47 tool definitions
├── client.py   # FreshBooks API client (httpx async)
└── auth.py     # OAuth2 flow + token persistence

Сервер использует MCP Python SDK с FastMCP для удобной регистрации инструментов. Все вызовы API выполняются через асинхронный клиент с автоматическим обновлением токенов.

Требования

• Python 3.10+

• Учетная запись FreshBooks (для разработки подойдет бесплатная пробная версия)

• Учетные данные OAuth-приложения FreshBooks

Лицензия

MIT