MCP-сервер Microsoft Business Central

MCP-сервер (Model Context Protocol) для Microsoft Dynamics 365 Business Central. Предоставляет AI-ассистентам прямой доступ к данным Business Central через правильно отформатированные вызовы API v2.0.

Возможности

• ✅ Правильные URL-адреса API: использует формат /companies(id)/resource (без сегмента ODataV4)

• ✅ Нулевая установка: запуск через npx — предварительная установка не требуется

• ✅ Аутентификация Azure CLI: использует существующую аутентификацию Azure CLI

• ✅ Аутентификация client credentials: аутентификация «служба-к-службе» для AI-агентов

• ✅ Чистые имена инструментов: без префиксов, просто get_schema, list_items и т.д.

• ✅ Полный CRUD: создание, чтение, обновление и удаление записей Business Central

Установка

Через npx (рекомендуется)

Установка не требуется! Настройте в Claude Desktop или Claude Code:

{
  "mcpServers": {
    "business-central": {
      "type": "stdio",
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@knowall-ai/mcp-business-central"],
      "env": {
        "BC_URL_SERVER": "https://api.businesscentral.dynamics.com/v2.0/{tenant-id}/{environment}/api/v2.0",
        "BC_COMPANY": "Your Company Name",
        "BC_AUTH_TYPE": "azure_cli"
      }
    }
  }
}

Примечание для Windows: используйте cmd с /c, как показано выше, для корректного выполнения npx.

Через Smithery

Установите через Smithery:

npx -y @smithery/cli install @knowall-ai/mcp-business-central --client claude

Локальная разработка

git clone https://github.com/knowall-ai/mcp-business-central.git
cd mcp-business-central
npm install
npm run build
node build/index.js

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

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

Получение значений конфигурации

1. Идентификатор клиента (Tenant ID): найдите в портале Azure → Azure Active Directory → Обзор

2. Среда (Environment): обычно Production или Sandbox

3. Имя компании: отображаемое имя, указанное в Business Central

Пример формата URL-адреса:

https://api.businesscentral.dynamics.com/v2.0/00000000-0000-0000-0000-000000000000/Production/api/v2.0

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

Рекомендация: используйте аутентификацию azure_cli — она проще в настройке и надежнее. Метод client_credentials также поддерживается, но имеет известные сложности с настройкой приложений Microsoft Entra в Business Central. Подробнее см. docs/TROUBLESHOOTING.adoc.

Вариант 1: Azure CLI (рекомендуется)

Самый простой и надежный метод аутентификации. Использует существующий вход в Azure CLI.

Предварительные требования:

• Установите Azure CLI: https://docs.microsoft.com/cli/azure/install-azure-cli

• Выполните вход: az login

• Проверьте доступ: az account get-access-token --resource https://api.businesscentral.dynamics.com

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

{
  "mcpServers": {
    "business-central": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@knowall-ai/mcp-business-central"],
      "env": {
        "BC_AUTH_TYPE": "azure_cli",
        "BC_URL_SERVER": "https://api.businesscentral.dynamics.com/v2.0/{tenant-id}/Production/api/v2.0",
        "BC_COMPANY": "My Company"
      }
    }
  }
}

Вариант 2: Client Credentials (служба-к-службе)

Для автоматизированных систем, которым требуется работа без участия пользователя. Этот метод использует поток client credentials OAuth 2.0.

Примечание: этот метод имеет известные сложности с настройкой. Настройка приложений Microsoft Entra в Business Central может быть сложной, и создание пользователя приложения может не работать должным образом. Подробные инструкции см. в docs/TROUBLESHOOTING.adoc.

Обзор настройки:

1. Создайте регистрацию приложения в Azure:

   • Перейдите в портал Azure → Azure Active Directory → Регистрация приложений

   • Создайте новую регистрацию (одноклиентскую)

   • Добавьте разрешение API: Dynamics 365 Business Central → app_access (разрешение приложения, НЕ делегированное)

   • Предоставьте согласие администратора на это разрешение

   • Добавьте URI перенаправления: https://businesscentral.dynamics.com/OAuthLanding.htm

2. Создайте секрет клиента:

   • В регистрации приложения перейдите в раздел «Сертификаты и секреты»

   • Создайте новый секрет клиента и сохраните его в безопасном месте

3. Настройте Business Central:

   • В Business Central найдите «Приложения Microsoft Entra»

   • Нажмите + Создать и введите идентификатор клиента вашего приложения

   • Задайте описание (оно станет именем пользователя приложения)

   • Установите состояние «Включено» — вы должны увидеть сообщение «Пользователь с именем '[Описание]' будет создан»

   • Добавьте наборы разрешений: D365 BUS FULL ACCESS (рекомендуется) или D365 READ

   • Оставьте поле «Компания» пустым для доступа ко всем компаниям

   • Нажмите «Предоставить согласие»

4. Проверьте настройку:

   • Пользователь приложения должен появиться в списке пользователей в Business Central

   • Если нет, см. docs/TROUBLESHOOTING.adoc для решений

Справочные материалы:

• Microsoft: Аутентификация служба-к-службе

• Аутентификация API Business Central

Доступные инструменты

1. get_schema

Получить метаданные OData для ресурса Business Central.

Параметры:

• resource (строка, обязательно): имя ресурса (например, customers, contacts, salesOpportunities)

Пример:

{
  "resource": "customers"
}

2. list_items

Список элементов с необязательной фильтрацией и постраничной разбивкой.

Параметры:

• resource (строка, обязательно): имя ресурса

• filter (строка, необязательно): выражение фильтра OData

• top (число, необязательно): максимальное количество возвращаемых элементов

• skip (число, необязательно): количество пропускаемых элементов для постраничной разбивки

Пример:

{
  "resource": "customers",
  "filter": "displayName eq 'Contoso'",
  "top": 10
}

3. get_items_by_field

Получить элементы, соответствующие значению конкретного поля.

Параметры:

• resource (строка, обязательно): имя ресурса

• field (строка, обязательно): имя поля для фильтрации

• value (строка, обязательно): значение для сопоставления

Пример:

{
  "resource": "contacts",
  "field": "companyName",
  "value": "Contoso Ltd"
}

4. create_item

Создать новый элемент в Business Central.

Параметры:

• resource (строка, обязательно): имя ресурса

• item_data (объект, обязательно): данные создаваемого элемента

Пример:

{
  "resource": "contacts",
  "item_data": {
    "displayName": "John Doe",
    "companyName": "Contoso Ltd",
    "email": "john.doe@contoso.com"
  }
}

5. update_item

Обновить существующий элемент.

Параметры:

• resource (строка, обязательно): имя ресурса

• item_id (строка, обязательно): идентификатор элемента (GUID)

• item_data (объект, обязательно): поля для обновления

Пример:

{
  "resource": "customers",
  "item_id": "1366066e-7688-f011-b9d1-6045bde9b95f",
  "item_data": {
    "displayName": "Updated Name"
  }
}

6. delete_item

Удалить элемент из Business Central.

Параметры:

• resource (строка, обязательно): имя ресурса

• item_id (строка, обязательно): идентификатор элемента (GUID)

Пример:

{
  "resource": "contacts",
  "item_id": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6"
}

Часто используемые ресурсы

• companies — информация о компаниях

• customers — записи о клиентах

• contacts — записи о контактах

• salesOpportunities — возможности продаж

• salesQuotes — коммерческие предложения

• salesOrders — заказы на продажу

• salesInvoices — счета на продажу

• items — элементы товаров/услуг

• vendors — записи о поставщиках

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

Подробные руководства по устранению неполадок см. в docs/TROUBLESHOOTING.adoc, где рассматриваются:

• Проблемы с аутентификацией (ошибки 401, проблемы с токенами)

• Сложности и известные проблемы настройки client_credentials

• Ошибки «Компания не найдена»

• Конфигурация для конкретной среды (Production vs Sandbox)

Разработка

# Install dependencies
npm install

# Build TypeScript
npm run build

# Watch mode for development
npm run dev

Лицензия

MIT

Вклад в проект

Приветствуются вопросы и pull request'ы: https://github.com/knowall-ai/mcp-business-central

Связанные проекты

• Спецификация MCP: modelcontextprotocol.io