business-central-mcp-server

Un servidor MCP que expone los datos de Dynamics 365 Business Central (en línea) a un cliente MCP (Claude Code, Claude Desktop, etc.): entornos, empresas y cualquier entidad accesible a través de la API estándar v2.0 o una API AL personalizada.

Se comunica con api.businesscentral.dynamics.com usando un token de Entra para esa misma audiencia. Con autenticación delegada (interactiva / cli / azure-powershell) no necesita registro de aplicación ni consentimiento de administrador: opera como el usuario que ha iniciado sesión, limitado por los conjuntos de permisos de Business Central de ese usuario.

Tools

Read (siempre activo)

Las API personalizadas publicadas desde extensiones AL son accesibles en todas partes mediante api_route: "{publisher}/{group}/{version}".

Exportación de documentos

Business Central sirve documentos generados y archivos subidos como flujos de medios OData, no como campos JSON. export_file obtiene esos bytes y los escribe en disco; la herramienta devuelve la ruta, el tamaño y el SHA-256 en lugar del contenido, de modo que un PDF grande nunca llega al contexto del modelo. Solo lee de BC, pero como escribe en el sistema de archivos local, se registra en el nivel write — establece BC_MCP_MODE=write para usarla.

Inspecciona primero el enlace de medios y luego descárgalo:

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

Rutas de medios útiles: pdfDocument/pdfDocumentContent en salesInvoices, salesCreditMemos y purchaseInvoices; content en attachments; picture en items y employees.

output_path puede ser un archivo o un directorio: un directorio (o un separador final) significa que el nombre del archivo se deriva del registro y del tipo de contenido detectado. Omítelo por completo para recurrir a BC_EXPORT_DIR y luego al directorio de trabajo. Los archivos existentes nunca se sobrescriben a menos que pases overwrite: true, y las descargas que superen max_bytes (64 MiB por defecto) se rechazan antes de escribir nada.

Write (BC_MCP_MODE=write)

Cada llamada de escritura se registra en stderr con marca de tiempo, herramienta, destino e identidad del llamante. Estas mutan datos reales del ERP: publicar un documento crea asientos contables que no se pueden eliminar simplemente. Apunta BC_DEFAULT_ENVIRONMENT a un sandbox mientras experimentas.

Destructivo (BC_MCP_MODE=write y BC_MCP_ALLOW_DELETE=true)

El nivel destructivo está desactivado por defecto. Cuando se activa, cada llamada es primero un plan: dry_run=true (el valor predeterminado) devuelve el registro que se eliminaría más un confirm_token de un solo uso; solo una segunda llamada con dry_run=false y ese token realiza la eliminación, protegida por un etag If-Match.

Related MCP server: Microsoft Business Central MCP Server

Instalación en Claude Desktop

Descarga business-central-mcp-server-<version>.mcpb desde la última versión y ábrelo. Eso es toda la instalación: sin clonar, sin npm install, sin Node en tu máquina. Claude Desktop incluye su propio runtime de Node y el paquete lleva sus dependencias.

El diálogo de instalación recopila:

Con el inicio de sesión interactive predeterminado, deja en blanco el ID de cliente y el secreto. El servidor recurre al cliente público de Azure CLI, abre tu navegador y actúa como el usuario que ha iniciado sesión bajo los conjuntos de permisos de Business Central de ese usuario. No hay registro de aplicación ni consentimiento de administrador que gestionar.

El aviso del navegador vuelve a aparecer en cada reinicio de Claude Desktop. Los tokens se mantienen solo en memoria; persistirlos requeriría un módulo nativo de caché de credenciales y un paquete separado por plataforma.

Compilar el paquete tú mismo

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 se niega a producir un paquete cuya versión de manifiesto no coincida con package.json, o cuya lista de herramientas declarada no coincida con lo que el servidor realmente registra.

Configuración (Claude Code y otros clientes MCP)

cd business-central-mcp-server
npm install

Regístralo con tu cliente MCP. Ejemplo de entrada en .claude.json (autenticación delegada, solo lectura):

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

Para permitir crear/actualizar registros e invocar acciones enlazadas, establece "BC_MCP_MODE": "write". Para permitir también la eliminación, añade "BC_MCP_ALLOW_DELETE": "true".

Establece BC_DEFAULT_COMPANY_ID a un valor de list_companies si trabajas en una sola empresa y quieres omitir company_id en cada llamada.

Establece BC_EXPORT_DIR para elegir dónde escribe export_file cuando una llamada omite output_path.

Consulta .env.example para la lista completa de variables de entorno, incluidos todos los modos de autenticación admitidos.

Notas de autenticación

• Delegado (recomendado): interactive, device-code, cli o azure-powershell. No se necesita registro de aplicación; el llamante actúa como el usuario que ha iniciado sesión, limitado por los conjuntos de permisos de BC y el acceso a empresas de ese usuario.

• Service principal: no interactivo, pero el SP debe estar registrado como una aplicación de Entra dentro de Business Central (página de Aplicaciones de Entra, con conjuntos de permisos asignados) antes de que el plano de datos lo acepte.

• list_environments usa la API de descubrimiento del centro de administración, que además requiere acceso al centro de administración de BC. Las demás herramientas funcionan sin él si pasas los nombres de entorno directamente.

Requisitos

• Una identidad de Entra con licencia para Business Central en el inquilino de destino.

• Node.js >= 20, si ejecutas desde el código fuente. El paquete de Claude Desktop no tiene ese requisito; Desktop proporciona el runtime.

Licencia

MIT — consulta LICENSE.