mcp-buchhaltungsbutler

Deutsch | English

MCP-сервер (Model Context Protocol), который открывает API BuchhaltungsButler (v1) — немецкого SaaS для бухгалтерского учёта — как набор подобранных, эффективных по токенам инструментов для LLM-агентов.

Неофициальный проект, созданный сообществом. Не имеет отношения к BuchhaltungsButler и не одобрен им.

Создан для агентов, а не просто обёртка над API

• 30 инструментов, покрывающих все 48 эндпоинтов — пакетные, списочные и единичные варианты одного действия объединены в один инструмент, чтобы ваше контекстное окно не заполнялось почти одинаковыми определениями инструментов.

• Минимализм по умолчанию — list-инструменты по умолчанию возвращают сокращённые, удобные для LLM поля; передавайте full: true, когда нужна полная запись.

• Без возни с массивами — позиции накладных, разбивки проводок и другие причуды API представлены в виде чистых обычных объектов. Больше не нужно вручную синхронизировать пять параллельных массивов.

• Всегда синхронно со спецификацией — определения эндпоинтов генерируются непосредственно из официальной спецификации API BuchhaltungsButler, а не поддерживаются вручную.

Related MCP server: Cuéntica MCP

Настройка

1. npm install

2. Скопируйте .env.example в .env и заполните BB_API_CLIENT, BB_API_SECRET, BB_API_KEY (BuchhaltungsButler → Settings → API).

3. npm test — работает против имитированных HTTP-ответов, реальные учётные данные не нужны.

4. npm run build && npm start — или npm run dev для быстрого локального запуска без предварительной сборки.

npm run generate пересоздаёт src/bb-client/generated/endpoints.ts из сохранённой спецификации (spec/buchhaltungsbutler-v1.json); результат уже закоммичен, так что команда нужна только после обновления самого файла спецификации.

Использование с MCP-клиентом

.env работает только для локальных запусков npm run dev/npm start. Настоящий MCP-клиент (например, Claude Desktop) сам запускает сервер и не читает .env — передавайте учётные данные через его собственную конфигурацию env. Пример записи в claude_desktop_config.json:

{
  "mcpServers": {
    "buchhaltungsbutler": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-buchhaltungsbutler/dist/index.js"],
      "env": {
        "BB_API_CLIENT": "your-api-client",
        "BB_API_SECRET": "your-api-secret",
        "BB_API_KEY": "your-customer-api-key"
      }
    }
  }
}

Сначала выполните npm run build, чтобы появился файл dist/index.js.

Инструменты

Архитектура

src/
  config.ts              # env var loading, fail-fast validation
  bb-client/
    generated/            # spec-derived endpoint metadata (regenerate with npm run generate)
    client.ts              # generic HTTP client: auth, api_key injection, error mapping
  formatting/trim.ts       # trims list responses to LLM-friendly fields
  tools/                   # one file per category, curated MCP tools on top of the client
  server.ts, index.ts      # MCP server bootstrap (stdio)
scripts/generate-client.ts # parses spec/buchhaltungsbutler-v1.json into src/bb-client/generated/

Однотенантная архитектура, только локальный stdio-транспорт — без удалённого хостинга, без мультитенантности, без OAuth. Учётные данные никогда не попадают в модель; клиентский слой подставляет их в запросы из переменных окружения.

Статус

Все 48 эндпоинтов BuchhaltungsButler покрыты 30 инструментами выше и протестированы на имитированных HTTP-ответах. Однако на живом аккаунте они пока не проверены — если вы столкнётесь с неожиданной ошибкой, особенно в четырёх эндпоинтах с суффиксом *_id_by_customer (get_receipt, set_receipt_deleted, get_transaction) или на add_receipt_postings/add_transaction_postings с пакетом, где батч мест затрат указан частично, пожалуйста, откройте issue.

Разработка

git clone https://github.com/si0nDE/mcp-buchhaltungsbutler.git && cd mcp-buchhaltungsbutler
npm install
npm test           # vitest run
npm run build       # tsc, strict mode