Business Central Sales Analysis MCP

Real-time sales analysis and business intelligence from Microsoft Dynamics 365 Business Central.

Description

This MCP connects directly to Business Central API to provide multidimensional sales analysis for Full Queso's three locations (FQ01 Chacao, FQ28 Marqués, FQ88 Candelaria).

Unlike traditional BI tools, this MCP provides:

• Proactive insights: Not just data, but actionable recommendations
• Natural language queries: Ask questions in plain Spanish/English
• Real-time analysis: Direct API connection, no exports needed
• Contextual intelligence: Understands business context and provides specific actions

Installation

cd /Users/fpmacbookm1/Documents/FullQuesoMCP-Main/mcp-bc-analisis-ventas
npm install

Configuration

1. Copy .env.example to .env:

cp .env.example .env

2. Fill in your Business Central credentials in .env:

BC_TENANT_ID=your-tenant-id
BC_CLIENT_ID=your-client-id
BC_CLIENT_SECRET=your-client-secret

3. Add to Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "fullqueso-bc-sales": {
      "command": "/opt/homebrew/opt/node@20/bin/node",
      "args": [
        "/Users/fpmacbookm1/Documents/FullQuesoMCP-Main/mcp-bc-analisis-ventas/server.js"
      ]
    }
  }
}

4. Restart Claude Desktop

Tools Available

get_sales_analysis

Multidimensional sales analysis by product, category, store, time period.

Example queries:

• "¿Cuánto vendimos esta semana?"
• "Muéstrame las ventas de Marqués por categoría"
• "Analiza las ventas del mes pasado comparado con el anterior"

get_product_performance

Detailed product performance analysis with growth trends and margins.

Example queries:

• "¿Cuáles son los productos más rentables?"
• "¿Qué productos están creciendo más?"
• "Dame los top 10 productos por volumen"

compare_stores

Compare performance across the three locations.

Example queries:

• "Compara las 3 tiendas este mes"
• "¿Por qué Chacao vende más que Marqués?"
• "¿Qué hace bien cada tienda?"

Usage Examples

User: "¿Qué productos debo promover esta semana en Marqués?"

Claude: [Uses get_sales_analysis and get_product_performance]

Response: "Basado en análisis de BC para Marqués (últimos 30 días):

TOP 3 PRODUCTOS PARA PROMOVER:

1. **Cachapa con queso**
   - Margen: 65% ($3.50 ganancia/unidad)
   - Tendencia: +18% vs mes pasado
   - Potencial: +$1,400/mes con 20 unidades más/día
   - ACCIÓN: Combo cachapa+jugo con 10% descuento

2. **Tequeños (porción 5)**
   - Margen: 58%
   - Repurchase rate: 40%
   - Sub-penetrado vs otras tiendas
   - ACCIÓN: Muestra gratis en horas pico
   
..."

Environment Variables

Required variables (see .env.example):

| Variable | Description | Example | |----------|-------------|---------| | BC_TENANT_ID | Azure AD Tenant ID | b8f42bfe-... | | BC_CLIENT_ID | Application Client ID | 43a7b68c-... | | BC_CLIENT_SECRET | Application Secret | UjN8Q~... | | BC_ENVIRONMENT | BC Environment | Production | | BC_COMPANY_FQ01 | FQ01 Company ID | 9fef8315-... | | BC_COMPANY_FQ28 | FQ28 Company ID | ae8a1983-... | | BC_COMPANY_FQ88 | FQ88 Company ID | 31054e8d-... |

Troubleshooting

MCP not appearing in Claude Desktop

• Check config file syntax (valid JSON)
• Verify node path: which node
• Restart Claude Desktop
• Check Claude Desktop logs

Authentication errors

• Verify credentials in .env
• Check app is registered in BC's "Microsoft Entra Applications"
• Verify D365 READ permission is granted
• Test API access manually (see Testing section)

No data returned

• Check date ranges are valid
• Verify company IDs are correct
• Check API connectivity
• Review server logs

Testing

Test BC API connection:

npm run test-connection

Test all 3 tools with real data:

npm run test-tools

Development

See CLAUDE.md for detailed development instructions and TODO.md for task checklist.

Architecture

• server.js: MCP server entry point
• bc-client.js: Business Central API client with token management
• tools/: Individual tool implementations
  • sales-analysis.js: Sales analysis tool
  • product-performance.js: Product performance tool
  • store-comparison.js: Store comparison tool
• utils/: Shared utilities
  • dates.js: Date range calculations and formatting
  • aggregation.js: Data aggregation and metrics
  • insights.js: Business insight generation

Performance

• Token caching: Reduces auth overhead
• Typical response time: 2-5 seconds
• Handles date ranges up to 1 year

Security

• All credentials stored in .env (never committed)
• Read-only access to BC (D365 READ permission)
• Tokens expire after 1 hour
• No data persistence (stateless)

Version

Current Version: 1.0.0
Last Updated: 2026-02-18

License

Proprietary - Full Queso Internal Use Only

Support

For issues or questions:

1. Check this README
2. Review CLAUDE.md documentation
3. Check Claude Desktop logs
4. Contact Francisco Padilla