moneybird-mcp

Сервер Model Context Protocol для бухгалтерского API Moneybird.

Он предоставляет Moneybird в виде набора MCP-инструментов, поэтому ассистент вроде Claude может искать контакты, читать счета, проверять банковские операции, отмечать время и получать отчёты из вашей администрации. Доступ только для чтения, пока вы не включите запись; инструменты сгруппированы в наборы, которые можно включать по отдельности, а клиент сам регулирует темп своих запросов, чтобы оставаться в пределах лимита частоты запросов Moneybird. Он использует stdio для локальных клиентов и Streamable HTTP для удалённых.

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

Зарегистрируйте сервер в вашем клиенте. Для Claude Code:

claude mcp add moneybird -- npx -y moneybird-mcp serve

Затем попросите ассистента подключиться. Сервер запускается без учётных данных и предоставляет инструмент connect_moneybird: он открывает страницу токенов Moneybird в вашем браузере, запрашивает токен, который вы там создаёте, проверяет его, выбирает вашу администрацию и сохраняет её — не выходя из диалога.

Для этого нужен клиент, поддерживающий MCP-elicitation (запрос недостающих данных). Если такой возможности нет, ту же настройку можно выполнить в терминале:

npx moneybird-mcp login

команда проведёт вас по тем же шагам и сохранит результат в ~/.config/moneybird-mcp/credentials.json.

Проверьте, что всё работает, прежде чем полагаться на него:

npx moneybird-mcp status

status выводит включённые наборы инструментов, настройки записи и удаления, источник учётных данных и администрации, доступные токену. Он завершается с ненулевым кодом, если не может связаться с Moneybird.

Related MCP server: kalender.digital MCP Server

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

Moneybird предлагает два способа получения токена, и этот сервер поддерживает оба. Ни один из них не является полностью автоматическим: Moneybird не реализует ни Dynamic Client Registration, ни PKCE, поэтому не существует процедуры, которая позволяла бы пропустить создание токена или регистрацию приложения. Это ограничение Moneybird API, а не этого сервера. Инструмент connect_moneybird убирает все шаги вокруг этого одного — он открывает нужную страницу и сохраняет результат за вас.

Персональный API-токен. Вы создаёте его сами на https://moneybird.com/user/applications/new, отмечаете нужные области доступа и вставляете его в moneybird-mcp login. Самый простой путь. Области доступа фиксируются при создании, и срок действия этих токенов не истекает — а значит, их нельзя автоматически ротировать. Относитесь к нему как к паролю.

OAuth-приложение. Вы регистрируете приложение там же, затем:

export MONEYBIRD_CLIENT_ID=...
export MONEYBIRD_CLIENT_SECRET=...
npx moneybird-mcp login --oauth

Сервер открывает страницу авторизации Moneybird, перехватывает перенаправление на http://127.0.0.1:51739/callback и обменивает код на токен. Moneybird сопоставляет redirect URI в точности, поэтому этот URI должен быть зарегистрирован в вашем приложении дословно. Используйте --port, чтобы выбрать другой, или --oob, чтобы Moneybird показал код в браузере вместо перенаправления, — это удобно, когда нельзя открыть loopback-прослушиватель. OAuth-токены можно отозвать в Moneybird; при наличии срока действия они обновляются автоматически.

Чтобы сохранить токен без запросов, например, в скрипте подготовки:

npx moneybird-mcp login --token "$MONEYBIRD_TOKEN"

moneybird-mcp logout удаляет сохранённый файл. Для учётных данных OAuth он не отзывает саму авторизацию — сделайте это в Moneybird.

См. docs/authentication.md — области доступа, поведение обновления и точные процедуры.

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

Конфигурация берётся из окружения; флаги CLI имеют приоритет над ней.

Переменные окружения

Команды

Флаги

Наборы инструментов

Инструменты сгруппированы по доменам Moneybird. Пять включены по умолчанию; остальные четыре требуют явного включения.

Задайте их явно, дополните набор по умолчанию или вычтите из него:

moneybird-mcp serve --toolsets core,invoicing     # exactly these two
moneybird-mcp serve --toolsets all                # everything
moneybird-mcp serve --toolsets reports            # exactly reports
moneybird-mcp serve --toolsets -banking,-time     # the defaults minus two

Элемент -name в любом месте списка означает, что список формируется на основе набора по умолчанию, а не с нуля. all имеет приоритет над всем остальным. Неизвестное имя — это ошибка, а не молчаливое игнорирование.

Полный список инструментов приведён в docs/tools.md; также можно выполнить moneybird-mcp tools.

Модель безопасности

Каждый инструмент объявляет один из трёх уровней доступа, и сервер регистрирует только те, которые разрешены текущими настройками. Незарегистрированный инструмент невидим для модели — его нельзя вызвать по ошибке или заставить появиться.

• read — всегда регистрируется.

• write — создаёт или изменяет данные. Требует --allow-write или MONEYBIRD_ALLOW_WRITE=true.

• destroy — требует --allow-delete и --allow-write. --allow-delete сам по себе ничего не делает.

Удаление контролируется отдельно от записи, потому что эти два типа сбоев несопоставимы. Ошибочная запись оставляет данные, которые можно исправить; удаление или отправленный клиенту счёт — это не то, что API может отменить. Включение записи, чтобы ассистент мог подготовить счёт, не должно также позволять ему удалять вашу бухгалтерию. Поэтому уровень destroy охватывает и удаления, и вызовы, которые на практике необратимы, например отправку документа контакту.

По умолчанию доступ только для чтения. Включите минимум необходимого:

claude mcp add moneybird --env MONEYBIRD_ALLOW_WRITE=true -- npx -y moneybird-mcp serve

Настройка клиента

Claude Code

claude mcp add moneybird -- npx -y moneybird-mcp serve

С доступом на запись и более широким набором инструментов:

claude mcp add moneybird \
  --env MONEYBIRD_ALLOW_WRITE=true \
  --env MONEYBIRD_TOOLSETS=all \
  -- npx -y moneybird-mcp serve

Claude Desktop

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

{
  "mcpServers": {
    "moneybird": {
      "command": "npx",
      "args": ["-y", "moneybird-mcp", "serve"],
      "env": {
        "MONEYBIRD_ALLOW_WRITE": "true"
      }
    }
  }
}

Файл находится в ~/Library/Application Support/Claude/claude_desktop_config.json на macOS и %APPDATA%\Claude\claude_desktop_config.json на Windows. После изменения перезапустите приложение.

Любой stdio-клиент

Сервер — это обычный stdio-сервер MCP. Запустите moneybird-mcp serve и общайтесь по JSON-RPC через stdin и stdout. Диагностика выводится в stderr, никогда в stdout.

{
  "command": "npx",
  "args": ["-y", "moneybird-mcp", "serve"],
  "env": {
    "MONEYBIRD_API_TOKEN": "..."
  }
}

Если вы предпочитаете не хранить учётные данные на диске, задайте MONEYBIRD_API_TOKEN в блоке env клиента. Он имеет приоритет над любыми данными в credentials.json.

Docker и самостоятельный хостинг

docker build -t moneybird-mcp .
docker run --rm -p 3000:3000 -e MONEYBIRD_API_TOKEN=... moneybird-mcp

Образ по умолчанию использует HTTP-транспорт на 0.0.0.0:3000 и открывает /mcp, а также неаутентифицированный /healthz. Не размещайте его на публичном адресе без аутентификации.

В docs/hosting.md описаны три режима HTTP-аутентификации, мультитенантные развёртывания passthrough, заметки об обратном прокси и подключение удалённого клиента.

Лимиты запросов

Moneybird разрешает 150 запросов за 5 минут на IP и 50 за 5 минут для конечных точек /reports. Клиент ведёт собственные счётчики скользящего окна для обоих бюджетов и задерживает запрос, который превысил бы один из них, поэтому при обычном использовании 429 не возникает. Если Moneybird всё же возвращает 429, клиент соблюдает Retry-After, а в противном случае выполняет экспоненциальную задержку с полным джиттером, до MONEYBIRD_MAX_RETRIES попыток.

Бюджет выделяется на IP, а не на токен. Несколько инстансов за одним исходящим адресом делят его, и локальные счётчики не видят друг друга. Планируйте развёртывания соответственно.

Разработка

npm install
npm run build      # before typecheck: the docs generator imports the built output
npm run typecheck
npm test
npm run format

docs/tools.md генерируется из определений инструментов. Перегенерируйте его после добавления или изменения инструмента:

npm run docs:tools

spec/endpoints.json фиксирует опубликованный список операций Moneybird, а тест сверяет с ним каждый путь, который вызывает инструмент. Обновляйте его, когда Moneybird выпускает изменения API:

npm run spec:refresh
npm test

Упавший тест конечных точек после обновления означает, что маршрут, от которого зависит инструмент, перемещён или удалён.

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

Issues и pull request'ы приветствуются на https://github.com/HalloSouf/moneybird-mcp. Пожалуйста, запустите npm run typecheck, npm test и npm run format:check перед открытием pull request; CI запускает те же проверки на Node 20 и 22.

Лицензия

MIT. См. LICENSE.