Servidor MCP de Microsoft Business Central

Servidor del Model Context Protocol (MCP) para Microsoft Dynamics 365 Business Central. Proporciona a los asistentes de IA acceso directo a los datos de Business Central mediante llamadas correctamente formateadas a la API v2.0.

Características

• ✅ URLs de API correctas: Utiliza el formato /companies(id)/resource (sin segmento ODataV4)

• ✅ Cero instalación: Ejecutar con npx - no requiere instalación previa

• ✅ Autenticación con Azure CLI: Aprovecha la autenticación existente de Azure CLI

• ✅ Autenticación con credenciales de cliente: Autenticación de servicio a servicio para agentes de IA

• ✅ Nombres de herramientas limpios: Sin prefijos, solo get_schema, list_items, etc.

• ✅ CRUD completo: Crear, leer, actualizar y eliminar registros de Business Central

Instalación

Usando npx (Recomendado)

¡No se necesita instalación! Configúralo en Claude Desktop o 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"
      }
    }
  }
}

Nota para Windows: Usa cmd con /c como se muestra arriba para una ejecución correcta de npx.

Usando Smithery

Instala a través de Smithery:

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

Desarrollo local

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

Configuración

Variables de entorno

Obtención de los valores de configuración

1. ID de inquilino: Encuéntralo en Azure Portal → Azure Active Directory → Información general

2. Entorno: Normalmente Production o Sandbox

3. Nombre de la empresa: El nombre para mostrar que aparece en Business Central

Ejemplo de formato de URL:

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

Autenticación

Recomendación: Usa la autenticación azure_cli - es más sencilla de configurar y más fiable. El método client_credentials también es compatible, pero tiene problemas de configuración conocidos con la configuración de Microsoft Entra Applications de Business Central. Consulta docs/TROUBLESHOOTING.adoc para más detalles.

Opción 1: Azure CLI (Recomendado)

El método de autenticación más sencillo y fiable. Utiliza tu inicio de sesión existente de Azure CLI.

Requisitos previos:

• Instalar Azure CLI: https://docs.microsoft.com/cli/azure/install-azure-cli

• Iniciar sesión: az login

• Verificar acceso: az account get-access-token --resource https://api.businesscentral.dynamics.com

Configuración:

{
  "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"
      }
    }
  }
}

Opción 2: Credenciales de cliente (Servicio a servicio)

Para sistemas automatizados que necesitan ejecutarse sin interacción del usuario. Este método utiliza el flujo de credenciales de cliente OAuth 2.0.

Nota: Este método tiene problemas de configuración conocidos. La configuración de "Microsoft Entra Applications" de Business Central puede ser compleja y la creación del usuario de aplicación puede no funcionar como se espera. Consulta docs/TROUBLESHOOTING.adoc para obtener una guía detallada.

Resumen de configuración:

1. Crear un registro de aplicación de Azure:

   • Ve a Azure Portal → Azure Active Directory → Registros de aplicaciones

   • Crea un nuevo registro (inquilino único)

   • Añade permiso de API: Dynamics 365 Business Central → app_access (permiso de aplicación, NO delegado)

   • Concede consentimiento de administrador para el permiso

   • Añade URI de redirección: https://businesscentral.dynamics.com/OAuthLanding.htm

2. Generar secreto de cliente:

   • En tu registro de aplicación, ve a Certificados y secretos

   • Crea un nuevo secreto de cliente y guárdalo de forma segura

3. Configurar Business Central:

   • En Business Central, busca "Microsoft Entra Applications"

   • Haz clic en + Nuevo e introduce el ID de cliente de tu aplicación

   • Establece una descripción (esto se convierte en el nombre de usuario de la aplicación)

   • Establece el estado en "Habilitado" - deberías ver "Se creará un usuario llamado '[Descripción]'"

   • Añade conjuntos de permisos: D365 BUS FULL ACCESS (recomendado) o D365 READ

   • Deja el campo Empresa en blanco para acceso a todas las empresas

   • Haz clic en "Conceder consentimiento"

4. Verificar la configuración:

   • El usuario de la aplicación debería aparecer en la lista de usuarios de Business Central

   • Si no es así, consulta docs/TROUBLESHOOTING.adoc para soluciones

Referencias:

• Microsoft: Autenticación de servicio a servicio

• Autenticación de API de Business Central

Herramientas disponibles

1. get_schema

Obtener metadatos OData para un recurso de Business Central.

Parámetros:

• resource (cadena, requerido): Nombre del recurso (por ejemplo, customers, contacts, salesOpportunities)

Ejemplo:

{
  "resource": "customers"
}

2. list_items

Listar elementos con filtrado y paginación opcionales.

Parámetros:

• resource (cadena, requerido): Nombre del recurso

• filter (cadena, opcional): Expresión de filtro OData

• top (número, opcional): Número máximo de elementos a devolver

• skip (número, opcional): Número de elementos a omitir para la paginación

Ejemplo:

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

3. get_items_by_field

Obtener elementos que coincidan con un valor de campo específico.

Parámetros:

• resource (cadena, requerido): Nombre del recurso

• field (cadena, requerido): Nombre del campo por el que filtrar

• value (cadena, requerido): Valor a coincidir

Ejemplo:

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

4. create_item

Crear un nuevo elemento en Business Central.

Parámetros:

• resource (cadena, requerido): Nombre del recurso

• item_data (objeto, requerido): Datos del elemento a crear

Ejemplo:

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

5. update_item

Actualizar un elemento existente.

Parámetros:

• resource (cadena, requerido): Nombre del recurso

• item_id (cadena, requerido): ID del elemento (GUID)

• item_data (objeto, requerido): Campos a actualizar

Ejemplo:

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

6. delete_item

Eliminar un elemento de Business Central.

Parámetros:

• resource (cadena, requerido): Nombre del recurso

• item_id (cadena, requerido): ID del elemento (GUID)

Ejemplo:

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

Recursos comunes

• companies - Información de la empresa

• customers - Registros de clientes

• contacts - Registros de contactos

• salesOpportunities - Oportunidades de venta

• salesQuotes - Presupuestos de venta

• salesOrders - Pedidos de venta

• salesInvoices - Facturas de venta

• items - Elementos de producto/servicio

• vendors - Registros de proveedores

Solución de problemas

Consulta docs/TROUBLESHOOTING.adoc para guías detalladas de solución de problemas que cubren:

• Problemas de autenticación (errores 401, problemas con tokens)

• Problemas de configuración de client_credentials y problemas conocidos

• Errores de empresa no encontrada

• Configuración específica del entorno (Production vs Sandbox)

Desarrollo

# Install dependencies
npm install

# Build TypeScript
npm run build

# Watch mode for development
npm run dev

Licencia

MIT

Contribuciones

Se aceptan problemas y solicitudes de extracción en https://github.com/knowall-ai/mcp-business-central

Proyectos relacionados

• Especificación MCP: modelcontextprotocol.io