MCP-сервер BuchPilot

MCP-сервер для бухгалтерского учета в регионе DACH — управляйте контактами, счетами, документами и коммерческими предложениями прямо из Claude, Cursor или любого другого MCP-совместимого клиента.

npm version License: MIT

Что это такое?

BuchPilot MCP — это сервер Model Context Protocol, который связывает вашу бухгалтерскую систему (в настоящее время Lexoffice) с ИИ-ассистентами. Вы можете создавать счета, управлять контактами и проверять просроченные платежи с помощью естественного языка — прямо в Claude Desktop, Cursor или любом другом MCP-клиенте.

Функции

15 инструментов для полной автоматизации бухгалтерского учета
Контакты: создание, получение, список, обновление
Счета: создание, получение, список, обновление, скачивание PDF
Первичные документы: создание, получение, список (входящие счета, кредитовые авизо)
Коммерческие предложения: создание, получение
Просроченные счета: с указанием сумм и количества дней просрочки
Архитектура бэкенда — в настоящее время Lexoffice, с возможностью расширения для sevDesk, Billomat и т. д.
Поддержка плагинов — возможность интеграции инструментов E-Invoice MCP (einvoice-mcp)
Без базы данных, без состояния — чистый API-прокси

Установка

Требования

Node.js >= 18
Аккаунт Lexoffice с API-ключом

npm (глобально)

npm install -g buchpilot-mcp

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

git clone https://github.com/makririch/buchpilot-mcp.git
cd buchpilot-mcp
npm install
npm run build

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

Создайте файл конфигурации .buchpilot.json в одном из следующих мест:

Путь из переменной окружения BUCHPILOT_CONFIG
~/.buchpilot.json (домашняя директория)
./.buchpilot.json (текущая директория)

Содержимое .buchpilot.json

{
  "backends": {
    "lexoffice": {
      "api_key": "DEIN_LEXOFFICE_API_KEY"
    }
  },
  "default_backend": "lexoffice"
}

Создание API-ключа Lexoffice

Перейдите в Lexoffice Public API
Нажмите API-Key erstellen (Создать API-ключ)
Скопируйте ключ и вставьте его в .buchpilot.json

Указание по безопасности: Никогда не сохраняйте API-ключ в Git. Добавьте .buchpilot.json в ваш .gitignore.

Использование

Запуск сервера (автономно)

# Nach npm install -g:
buchpilot-mcp

# Oder von Source:
npm start

# Entwicklung mit Auto-Reload:
npm run dev

Сервер работает через stdio и ожидает MCP-сообщения.

Использование в Claude Desktop

См. Руководство по настройке Claude Desktop для получения подробных инструкций.

Краткая версия — добавьте в claude_desktop_config.json:

{
  "mcpServers": {
    "buchpilot": {
      "command": "npx",
      "args": ["-y", "buchpilot-mcp"],
      "env": {
        "BUCHPILOT_CONFIG": "/Users/DEIN_NAME/.buchpilot.json"
      }
    }
  }
}

Примеры (естественный язык в Claude)

После настройки сервера вы можете спросить Claude, например:

"Erstelle einen Kontakt fuer die Firma Beispiel GmbH mit der E-Mail info@beispiel.de" (Создай контакт для компании Beispiel GmbH с email info@beispiel.de)
"Zeige mir alle offenen Rechnungen" (Покажи мне все открытые счета)
"Erstelle eine Rechnung an Kontakt XYZ: 10 Stunden Beratung zu je 150 EUR" (Создай счет для контакта XYZ: 10 часов консультаций по 150 евро)
"Welche Rechnungen sind ueberfaellige?" (Какие счета просрочены?)
"Lade die PDF von Rechnung ABC herunter" (Скачай PDF счета ABC)
"Erstelle ein Angebot fuer 5 Lizenzen a 49 EUR/Monat" (Создай предложение на 5 лицензий по 49 евро в месяц)

Справочник инструментов

Полный справочник всех 15 инструментов с параметрами, примерами входных и выходных данных можно найти в docs/tool-reference.md.

Краткий обзор

Инструмент	Описание
`create_contact`	Создать новый контакт (физическое или юридическое лицо)
`get_contact`	Получить контакт по ID
`list_contacts`	Список контактов с фильтрами
`update_contact`	Обновить контакт
`create_invoice`	Создать новый счет с позициями
`get_invoice`	Получить счет по ID
`list_invoices`	Список счетов (с фильтрацией по статусу)
`get_invoice_pdf`	Скачать счет в формате PDF (Base64)
`update_invoice`	Обновить черновик счета
`create_voucher`	Создать новый первичный документ
`get_voucher`	Получить документ по ID
`list_vouchers`	Список документов
`create_quotation`	Создать новое предложение с позициями
`get_quotation`	Получить предложение по ID
`get_overdue_invoices`	Просроченные счета с анализом

Интеграция E-Invoice

BuchPilot MCP может опционально интегрировать пакет E-Invoice MCP для создания XRechnung и ZUGFeRD прямо из бухгалтерской системы:

// In deinem eigenen MCP-Server:
import { registerEInvoiceTools } from "einvoice-mcp";
registerEInvoiceTools(server);
// Ergebnis: 15 + 4 = 19 Tools

FAQ / Устранение неполадок

"No .buchpilot.json found"

Сервер не находит файл конфигурации. Создайте .buchpilot.json в вашей домашней директории:

echo '{"backends":{"lexoffice":{"api_key":"DEIN_KEY"}},"default_backend":"lexoffice"}' > ~/.buchpilot.json

"401 Unauthorized" в Lexoffice

Правильно ли указан API-ключ в .dachflow.json?
Активен ли ключ? Проверьте в Lexoffice Public API
API-ключи могут истекать — при необходимости создайте новый

"429 Too Many Requests"

Lexoffice разрешает макс. 2 запроса в секунду. Если вы выполняете много операций подряд, сделайте небольшую паузу между запросами.

Сервер запускается, но Claude не распознает инструменты

Проверьте правильность claude_desktop_config.json
Перезапустите Claude Desktop после внесения изменений в конфигурацию
Проверьте логи: ~/Library/Logs/Claude/mcp.log (macOS)

Счет не может быть обновлен

Обновлять можно только счета со статусом draft (черновик). Финализированные счета неизменяемы.

Бэкенд "sevDesk" недоступен

В настоящее время поддерживается только Lexoffice. Поддержка sevDesk запланирована. Вы можете использовать узлы n8n (n8n-nodes-buchpilot) для sevDesk.

Лицензия

MIT — свободно для использования, в том числе в коммерческих целях.

Автор

MaKri — GitHub

buchpilot-mcp