bokio-mcp

Сервер MCP для бухгалтерского API Bokio. Он предоставляет 85 инструментов для одной компании Bokio — счета, клиенты, поставщики, счета поставщиков, журнальные записи, кредит-ноты, план счетов, финансовые годы, позиции, теги, загрузки, экспорт SIE и банковские платежи — так что MCP-клиент может читать и (опционально) записывать вашу бухгалтерию.

Никаких учётных записей, баз данных или облачных сервисов. Одна компания на экземпляр сервера.

"Which invoices are still unpaid?"
"Book the attached receipt against account 6570."
"Export the SIE file for the 2025 fiscal year."

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

Попробуйте с фикстурами, без учётной записи Bokio:

BOKIO_MOCK=true npx bokio-mcp status
# { "companyName": "Testbolaget AB", "status": "active", ... }

BOKIO_MOCK=true запускает встроенный фейковый Bokio, так что весь набор инструментов работает до получения учётных данных.

Для реальных данных выберите один из двух способов получения учётных данных ниже и добавьте сервер в ваш MCP-клиент.

Способ A — приватный токен интеграции (рекомендуется)

В Bokio: настройки компании → Интеграции → Токены API → Создать приватную интеграцию. Токен долгоживущий, привязан к этой одной компании и не требует проверки OAuth.

{
  "mcpServers": {
    "bokio": {
      "command": "npx",
      "args": ["-y", "bokio-mcp"],
      "env": {
        "BOKIO_INTEGRATION_TOKEN": "your-token",
        "BOKIO_COMPANY_ID": "the-company-uuid-from-the-bokio-url"
      }
    }
  }
}

Способ B — OAuth

Зарегистрируйте интеграцию в портале разработчика Bokio с URI перенаправления http://127.0.0.1:7337/callback, затем:

export BOKIO_CLIENT_ID=... BOKIO_CLIENT_SECRET=...
npx bokio-mcp login

Это откроет Bokio в вашем браузере и запишет токены в ~/.config/bokio-mcp/tokens.json (режим 0600). Токены доступа обновляются автоматически, включая ротацию refresh-токенов. Укажите вашему MCP-клиенту npx -y bokio-mcp с теми же двумя переменными окружения.

Related MCP server: QuickBooks Online MCP Server

Запись по умолчанию отключена

Свежая установка может читать, но не писать. Изменяющие инструменты не просто заблокированы — они отсутствуют в tools/list, поэтому модель никогда не предложит изменение, которое не может выполнить:

BOKIO_ALLOW_WRITES=true

Из 85 инструментов 38 — только для чтения, а 47 изменяют данные. Начните без флага, убедитесь, что модель читает то, что вы ожидаете, затем включите запись.

Команды

HTTP-транспорт

Для самостоятельного размещения, например, за обратным прокси или в контейнере:

MCP_AUTH_TOKEN=$(openssl rand -hex 32) bokio-mcp serve --http

/mcp защищён этим статическим bearer-токеном. Без MCP_AUTH_TOKEN сервер привязывается только к 127.0.0.1, а не открывает неаутентифицированный мост к живым бухгалтерским данным. Включён Dockerfile; по умолчанию он использует этот транспорт.

Окружение

См. .env.example для аннотированной версии.

Примечание о хранении токенов

Файл токенов OAuth хранится в открытом виде с режимом 0600, если не задан BOKIO_TOKEN_ENCRYPTION_KEY — та же позиция, что и у CLI gh и aws. На личной машине ключ, хранящийся рядом с тем, что он шифрует, даёт мало пользы; задавайте его, когда файл находится в менее приватном месте, например, в образе контейнера или на общем хосте.

Разработка

npm install
npm test          # 36 tests, no database, no credentials
npm run typecheck
npm run dev       # tsx watch, stdio transport

BOKIO_MOCK=true направляет каждый запрос Bokio во встроенный мок на уровне fetch, поэтому он ведёт себя одинаково под stdio, под HTTP и в тестах без запущенного сервера. test/mcp.test.ts прогоняет реальный протокол MCP от начала до конца против него.

Определения инструментов написаны вручную в src/tools/bokio/, но путь и метод каждого проверяются по спецификации OpenAPI во время компиляции с помощью хелпера op() — опечатка в маршруте приводит к ошибке сборки. Перегенерируйте типы спецификации с помощью:

npm run gen:bokio

Не поддерживается

• Более одной компании на экземпляр. Учётные данные Bokio привязаны к компании; запустите второй экземпляр для второй компании.

• Расширенные области. bank-payments:* требует одобрения интеграции от Bokio. Инструменты банковских платежей зарегистрированы, но будут давать сбой, пока ваша интеграция не одобрена и области не добавлены в BOKIO_SCOPES.

Лицензия

MIT