business-central-mcp-server

Сервер MCP, который предоставляет данные Dynamics 365 Business Central (online) MCP-клиенту (Claude Code, Claude Desktop и т. д.) — среды, компании и любые сущности, доступные через стандартный API v2.0 или пользовательский AL API.

Он взаимодействует с api.businesscentral.dynamics.com, используя токен Entra для той же аудитории. При делегированной аутентификации (interactive / cli / azure-powershell) не требуется регистрация приложения и согласие администратора — он работает от имени вошедшего пользователя, ограниченного наборами разрешений Business Central этого пользователя.

Tools

Read (always on)

Пользовательские API, опубликованные из расширений AL, доступны везде через api_route: "{publisher}/{group}/{version}".

Exporting documents

Business Central предоставляет сгенерированные документы и загруженные файлы как потоки мультимедиа OData, а не как поля JSON. export_file получает эти байты и записывает их на диск; инструмент возвращает путь, размер и SHA-256, а не содержимое, поэтому большой PDF никогда не попадает в контекст модели. Он только читает из BC, но поскольку записывает в локальную файловую систему, он регистрируется в уровне write — установите BC_MCP_MODE=write, чтобы использовать его.

Сначала проверьте ссылку на мультимедиа, затем скачайте её:

// get_entity — confirm the invoice has a renderable PDF
{ "entity_set": "salesInvoices", "record_id": "<guid>", "sub_path": "pdfDocument" }

// export_file — write the bytes out
{
  "entity_set": "salesInvoices",
  "record_id": "<guid>",
  "sub_path": "pdfDocument/pdfDocumentContent",
  "output_path": "./exports"
}

Полезные пути к мультимедиа: pdfDocument/pdfDocumentContent для salesInvoices, salesCreditMemos и purchaseInvoices; content для attachments; picture для items и employees.

output_path может быть файлом или каталогом — каталог (или завершающий разделитель) означает, что имя файла формируется из записи и определенного типа содержимого. Если его полностью опустить, используется BC_EXPORT_DIR, затем рабочая директория. Существующие файлы никогда не перезаписываются, если не передать overwrite: true, а загрузки, превышающие max_bytes (по умолчанию 64 МиБ), отклоняются до записи чего-либо.

Write (BC_MCP_MODE=write)

Каждый вызов записи регистрируется в stderr с отметкой времени, инструментом, целью и идентификатором вызывающего. Эти операции изменяют реальные данные ERP — публикация документа создает записи главной книги, которые нельзя просто удалить. Укажите BC_DEFAULT_ENVIRONMENT на песочницу при экспериментах.

Destructive (BC_MCP_MODE=write and BC_MCP_ALLOW_DELETE=true)

Деструктивный уровень отключен по умолчанию. При включении каждый вызов сначала является планом: dry_run=true (по умолчанию) возвращает запись, которая будет удалена, плюс одноразовый confirm_token; только второй вызов с dry_run=false и этим токеном выполняет удаление, защищенное If-Match etag.

Related MCP server: Microsoft Business Central MCP Server

Install in Claude Desktop

Скачайте business-central-mcp-server-<version>.mcpb из последнего релиза и откройте его. Это вся установка — не нужно клонировать репозиторий, выполнять npm install или иметь Node на вашей машине. Claude Desktop поставляется со своей средой выполнения Node, а пакет содержит свои зависимости.

Диалог установки собирает:

При входе по умолчанию interactive оставьте идентификатор клиента и секрет пустыми. Сервер использует публичный клиент Azure CLI, открывает ваш браузер и действует от имени вошедшего пользователя с наборами разрешений Business Central этого пользователя. Не требуется регистрация приложения и согласие администратора.

Запрос браузера появляется при каждом перезапуске Claude Desktop. Токены хранятся только в памяти; их сохранение потребовало бы нативного модуля кэша учетных данных и отдельного пакета для каждой платформы.

Building the bundle yourself

npm ci
npm run build:mcpb    # writes dist/business-central-mcp-server-<version>.mcpb
npm run verify:mcpb   # unpacks it and boots the server the way Desktop would

build:mcpb отказывается создавать пакет, если версия манифеста не совпадает с package.json, или если объявленный список инструментов не совпадает с тем, что сервер фактически регистрирует.

Setup (Claude Code and other MCP clients)

cd business-central-mcp-server
npm install

Зарегистрируйте его в вашем MCP-клиенте. Пример записи в .claude.json (делегированная аутентификация, только чтение):

{
  "mcpServers": {
    "business-central": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/business-central-mcp-server/index.js"],
      "env": {
        "AZURE_TENANT_ID": "<your-entra-tenant-id>",
        "BC_AUTH_MODE": "interactive",
        "BC_MCP_MODE": "read",
        "BC_DEFAULT_ENVIRONMENT": "Production"
      }
    }
  }
}

Чтобы разрешить создание/обновление записей и вызов связанных действий, установите "BC_MCP_MODE": "write". Чтобы также разрешить удаление, добавьте "BC_MCP_ALLOW_DELETE": "true".

Установите BC_DEFAULT_COMPANY_ID в значение из list_companies, если вы работаете в одной компании и хотите опускать company_id при каждом вызове.

Установите BC_EXPORT_DIR, чтобы выбрать, куда export_file записывает файлы, когда вызов опускает output_path.

См. .env.example для полного списка переменных окружения, включая все поддерживаемые режимы аутентификации.

Auth notes

• Делегированная (рекомендуется): interactive, device-code, cli или azure-powershell. Регистрация приложения не требуется; вызывающий действует от имени вошедшего пользователя, ограниченного наборами разрешений BC и доступом к компаниям этого пользователя.

• Субъект-служба: неинтерактивный, но субъект-служба должна быть зарегистрирована как приложение Entra внутри Business Central (страница приложений Entra, с назначенными наборами разрешений), прежде чем плоскость данных примет его.

• list_environments использует API обнаружения центра администрирования, который дополнительно требует доступа к центру администрирования BC. Остальные инструменты работают без него, если передавать имена сред напрямую.

Requirements

• Удостоверение Entra с лицензией на Business Central в целевом клиенте.

• Node.js >= 20, если вы запускаете из исходного кода. Пакет Claude Desktop не требует этого; Desktop предоставляет среду выполнения.

License

MIT — см. LICENSE.