@fullqueso/mcp-bc-gastos

v1.33.0

Published

22 days ago

MCP server for Business Central operational expense analysis, bank reconciliation, POS reconciliation, accounts receivable/payable, multi-payment draft visibility, payroll, inventory cost analysis, and manager reports - Full Queso franchise stores

@fullqueso/mcp-bc-gastos

MCP server for Microsoft Business Central — operational expenses, bank reconciliation, POS reconciliation, and accounts receivable/payable. Built for the Full Queso franchise (3 stores: FQ01 Chacao, FQ28 Marques, FQ88 Candelaria).

22 tools across 4 domains, powered by 3 BC API integrations.

Features

Expense Analysis — Breakdown by 10 categories, efficiency ratios, store comparison, anomaly detection, 6-month trends
Drill-Down & Vendors — Transaction-level detail with vendor lookup, per-account ledger, vendor directory
Bank Reconciliation — Unmatched statement lines/ledger entries, match scoring, journal entry suggestions, multi-bank POS reconciliation (Banesco, Bancrecer, BDV, UBII)
Accounts Receivable & Payable — Customer/vendor ledger entries, open receivables/payables with aging, collection status

Installation

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "fullqueso-bc-gastos": {
      "command": "npx",
      "args": ["-y", "@fullqueso/mcp-bc-gastos"],
      "env": {
        "BC_TENANT_ID": "your-azure-tenant-id",
        "BC_CLIENT_ID": "your-azure-app-client-id",
        "BC_CLIENT_SECRET": "your-azure-app-client-secret",
        "BC_TOKEN_URL": "https://login.microsoftonline.com/YOUR_TENANT/oauth2/v2.0/token",
        "BC_SCOPE": "https://api.businesscentral.dynamics.com/.default",
        "BC_API_BASE": "https://api.businesscentral.dynamics.com/v2.0",
        "BC_ENVIRONMENT": "production",
        "BC_COMPANY_FQ01": "company-guid-fq01",
        "BC_COMPANY_FQ28": "company-guid-fq28",
        "BC_COMPANY_FQ88": "company-guid-fq88",
        "BC_COMPANY_FQFR": "company-guid-franquicias"
      }
    }
  }
}

Local Development

git clone https://github.com/Fullqueso/fullqueso-mcp-bc-gastos.git
cd fullqueso-mcp-bc-gastos
npm install
cp .env.example .env
# Edit .env with your credentials
npm start

Tools (58)

Sección generada por scripts/generate-tools-doc.mjs — no editar a mano. Regenerar con: node scripts/generate-tools-doc.mjs --write

Expense Analysis & Core (11 tools)

compare_stores

Compara la eficiencia de gastos entre las tiendas de Full Queso (FQ01 Chacao, FQ28 Marqués, FQ88 Candelaria).

Params: period, month, start_date, end_date

detect_anomalies

Detecta anomalías en los gastos operacionales de Full Queso: gastos por encima de benchmarks, incrementos inusuales vs periodo anterior, concentración excesiva en una cuenta, y alertas de margen.

Params: period, month, start_date, end_date, stores, sensitivity

get_account_transactions

Listado completo de transacciones para una cuenta contable específica con balance running y nombre de proveedor.

Params: account_number, store, start_date, end_date

get_crm_rate

Obtiene la tasa de cambio Bs/USD desde el CRM de Full Queso (hora Caracas).

Params: coin*, date

get_efficiency_ratios

Calcula ratios de eficiencia financiera de Full Queso: gastos/ingresos, nómina/ingresos, alquiler/ingresos, servicios/ingresos, marketing/ingresos y margen operativo.

Params: period, month, start_date, end_date, stores

get_exchange_rate

Obtiene la tasa de cambio USD → VES desde Business Central.

Params: store*, date, start_date, end_date

get_expense_analysis

Análisis detallado de gastos operacionales de Full Queso por categoría (nómina, alquiler, servicios, marketing, etc.) con números de cuenta específicos.

Params: period, month, start_date, end_date, stores

get_expense_details

Drill-down de transacciones individuales de gastos operacionales.

Params: store*, period, month, start_date, end_date, category, account_number, min_amount, vendor_search, limit, offset

get_trends

Análisis de tendencias históricas de gastos e ingresos de Full Queso.

Params: months, store

get_vendor_transactions

Todas las transacciones de gastos operacionales de un proveedor específico.

Params: store, vendor_search, start_date, end_date

list_vendors

Lista todos los proveedores activos de una tienda en un periodo, con monto total pagado y número de transacciones.

Params: store*, start_date, end_date

Auditoría / POS Reconciliation (11 tools)

find_potential_matches

Para una línea no conciliada del banco, busca posibles correspondencias en las entradas contables de BC por monto, fecha y descripción.

Params: store, bank_account, statement_amount, transaction_date, description, date_tolerance_days, amount_tolerance_pct

get_bank_ledger_entries

Todos los movimientos del libro de banco (abiertos y cerrados) para una cuenta bancaria.

Params: store, bank_account, date_from, date_to, open_only

get_bank_reconciliation_report

Reporte consolidado de reconciliación bancaria: progreso de todos los statements abiertos, líneas no conciliadas (débitos y créditos por separado), y sugerencias de asientos contables para débitos.

Params: store, bank_account, statement_no, month, min_amount, include_suggestions, save_to_file, excel_output

get_gl_account_entries

Movimientos del libro mayor (G/L) para una cuenta específica.

Params: store, gl_account, date_from, date_to

get_pm_receipts

Recibos de Pago Móvil (PM) registrados en BC para una cuenta bancaria.

Params: store, bank_account, date_from, date_to

get_reconciliation_status

Resumen del estado de reconciliaciones bancarias abiertas: total líneas, conciliadas, pendientes y diferencia.

Params: store*, bank_account

get_unmatched_ledger_entries

Entradas contables del banco en BC sin correspondencia en el estado de cuenta.

Params: store, bank_account, date_from, date_to

get_unmatched_statement_lines

Líneas del estado de cuenta bancario NO conciliadas con entradas en BC.

Params: store, bank_account, statement_no, min_amount, type_filter

list_bank_accounts

Lista las cuentas bancarias de una tienda Full Queso.

Params: store*

reconcile_pos_sales

Conciliación automática de ventas POS: cruza montos bancarios de BC (BankAccountLedgerEntries) con liquidaciones bancarias por número de lote, agrupa por liquidación bancaria (settlement batches), calcula comisiones reales.

Params: store, start_date, end_date*, bank_account

suggest_journal_entries

Para pagos del banco sin correspondencia en BC, sugiere asientos contables basándose en la descripción y patrones históricos.

Params: store, bank_account, statement_no, auto_categorize

Cierre Mensual Bancario (6 tools)

generate_closing_journal

Genera el EXCEL del CIERRE MENSUAL bancario (mes completo, multi-banco).

Params: store, month, output_dir, allow_partial, strict

get_closing_match_results

CIERRE MENSUAL bancario: vista paginada de las 4 listas con auto-clasificación.

Params: store, month, list, bank_account, category, source, confidence, min_abs_amount_ves, sort, limit, offset

get_closing_questionnaire

CIERRE MENSUAL bancario: vista paginada/filtrada de las entradas del cuestionario del MES.

Params: store, month, bucket, counterparty_no, bank_account, status_filter, min_abs_amount_ves, min_abs_amount_usd, limit, offset, sort, pair_by_amount, pair_tolerance_pct, pair_max_days, description_regex

reconcile_closing_with_bc

CIERRE MENSUAL bancario: refresca el estado contra BC para detectar drift desde la última corrida.

Params: store, month

start_month_closing

CIERRE MENSUAL bancario (mes completo, multi-banco) en Business Central.

Params: store*, month, force_refresh

submit_closing_answers

CIERRE MENSUAL bancario: registra respuestas/aprobaciones al cuestionario del MES.

Params: store, month, user, answers*

Cobranzas (AR / AP) (7 tools)

get_collection_status

Verificación rápida del estado de cobranza de un período específico.

Params: store, start_date, end_date*

get_customer_balances

Lista clientes con saldos pendientes, montos vencidos y estado de cobranza.

Params: store*, only_with_balance, customer_number

get_customer_ledger

Movimientos del libro mayor de clientes: facturas emitidas, pagos recibidos, notas de crédito.

Params: store, start_date, end_date*, customer_number, document_type, open_only

get_customer_list

Lista de clientes con número, nombre y RIF (taxRegistrationNumber).

Params: store*, customer_number

get_open_payables

Resumen de todas las cuentas por pagar abiertas.

Params: store*, as_of_date, vendor_number, min_amount

get_open_receivables

Resumen rápido de todas las cuentas por cobrar abiertas.

Params: store*, as_of_date, customer_number, min_amount

get_vendor_ledger

Movimientos del libro mayor de proveedores: facturas recibidas, pagos realizados, notas de crédito.

Params: store, start_date, end_date*, vendor_number, document_type, open_only

Financial Statements & Cash Flow (3 tools)

get_cash_flow

Free Cash Flow (FCF) por método indirecto para una o más tiendas Full Queso (FQ01, FQ28, FQ88).

Params: stores, period, month, start_date, end_date, compare_previous, include_cash_position, render_html, output_path, open_browser, inline_html

get_financial_statements

Estado financiero completo (P&L / Profit & Loss) para una o más tiendas Full Queso (FQ01, FQ28, FQ88, FQFR) en un período.

Params: stores, period, month, start_date, end_date, render_html, compare_previous, output_path, open_browser, inline_html

get_income_statement

Estado de resultados (Income Statement) en el formato EXACTO del reporte Power BI "Income Statement by Month" (G/L Account Level 1) para una tienda Full Queso (FQ01, FQ28, FQ88) y un mes.

Params: store, stores, period, month, start_date, end_date, level

Inventario (7 tools)

get_inventory_by_location

Inventario desglosado por ubicación (Location Code) dentro de una tienda.

Params: store*, location_code, item_category, classification, as_of_date

get_inventory_change

Cambio de inventario WoW (semana) o MoM (mes).

Params: store, period, periods_back, item_category, classification

get_inventory_levels

Niveles de inventario agrupados por itemCategoryCode y/o inventoryPostingGroupCode (congelados, importado, local).

Params: store*, item_category, classification, as_of_date

get_item_card

Datos maestros de ítems de inventario: unitCost (BC), calculated_unit_cost (real desde últimas entradas), inventory qty, unitPrice, categoría.

Params: store*, item_number, item_search, item_category

get_item_cost_analysis

Análisis de costo de un ítem — calcula costo promedio ponderado de entradas recientes (compras, ensamblaje, ajustes positivos), compara con el unitCost actual de BC, y muestra el historial de costos por mes.

Params: store, item_number, months

get_item_cost_trend

Tendencia de costo de ítems: compara weighted avg inbound cost de últimas 2 semanas vs últimas 4 semanas.

Params: store*, item_number, item_category, period_days

get_item_ledger_entries

Entradas del libro de artículos (Item Ledger Entries) — historial de movimientos de inventario con costo real por entrada.

Params: store, item_number, entry_type, start_date, end_date, top

Draft Visibility (Multi-Payments + facturas sin postear) (4 tools)

get_draft_payables

Muestra facturas de compra abiertas clasificadas en tres niveles: totalmente pendientes (sin documento de pago), con Purch.

Params: store*, status_filter, vendor_number, include_lines, report, summary_only, save_to_file, excel_output

get_draft_receivables

Muestra facturas de venta abiertas clasificadas en tres niveles: totalmente pendientes (sin documento de cobro), con Multi-Payment en borrador (Open o Transferred), y el monto neto realmente sin cubrir.

Params: store*, status_filter, customer_number, include_lines, report, summary_only, save_to_file, excel_output

get_draft_summary

Resumen ejecutivo consolidado de todos los Multi-Payments en borrador (Open y Transferred) para una o todas las tiendas.

Params: store*

get_unposted_invoices

Facturas de compra y/o venta SIN POSTEAR en Business Central (status Draft o In Review).

Params: store*, type, start_date, end_date, include_in_review, summary_only

Nómina (3 tools)

get_employees

Lista empleados de una tienda con datos de nomina: tipo, status, salarios base, bonos predeterminados, fechas.

Params: store*, status, payroll_type, exclude_managerial, employee_search, employee_code

get_payroll_documents

Lista documentos de nomina (headers) con filtros por periodo, tipo, status.

Params: store*, period_code, payroll_type, exclude_managerial, status, start_date, end_date, include_employee_count, summary_only

get_payroll_lines

Detalle de nomina por empleado para un documento.

Params: store, document_no, employee_code, employee_search

Reports (2 tools)

generate_cxp_report

Genera reporte Excel de Cuentas por Pagar con 3 hojas: Sin Draft, Draft No Posteado, Pago Parcial + hoja Resumen con desglose por proveedor.

Params: store*, output_path

generate_manager_report

Genera el Reporte Gerente HTML completo para una tienda FQ.

Params: store*, date, output_path, open_browser, payroll_days

Ventas (4 tools)

compare_sales_by_store

Comparación de rendimiento de VENTAS entre las tiendas de Full Queso (FQ01 Chacao, FQ28 Marqués, FQ88 Candelaria).

Params: period, month, start_date, end_date, metrics

get_item_sales_detail

Detalle de ventas por ítem específico (1–50 SKUs) con granularidad día/semana/mes/total y desglose por tienda.

Params: items, start_date, end_date*, stores, granularity, include_zero_days

get_product_performance

Análisis detallado de rendimiento de productos de Full Queso.

Params: period, month, start_date, end_date, stores, sort_by, top_n

get_sales_analysis

Análisis multidimensional de ventas de Full Queso.

Params: period, month, start_date, end_date, stores, dimensions, metrics

Los params marcados con * son requeridos. Detalle completo en docs/tool_*.md.

API Integrations

| API | Used By | URL Pattern | |-----|---------|-------------| | Standard v2.0 | Expenses, vendors, customers | v2.0/{tenant}/{environment}/api/v2.0/companies({guid})/... | | OData V4 | Bank reconciliation, BALE | ODataV4/Company('{name}')/{service} | | Finance Reports Beta | Customer/vendor ledger entries | api/microsoft/reportsFinance/beta/companies({guid})/... |

All APIs share the same OAuth 2.0 credentials (Azure AD client credentials flow).

Environment Variables

| Variable | Required | Description | |---|---|---| | BC_TENANT_ID | Yes | Azure AD tenant ID | | BC_CLIENT_ID | Yes | Azure AD app client ID | | BC_CLIENT_SECRET | Yes | Azure AD app client secret | | BC_TOKEN_URL | Yes | OAuth 2.0 token endpoint | | BC_SCOPE | Yes | BC API scope | | BC_API_BASE | Yes | BC API base URL | | BC_ENVIRONMENT | Yes | BC environment (e.g., production) | | BC_COMPANY_FQ01 | Yes | Company GUID for store FQ01 | | BC_COMPANY_FQ28 | No | Company GUID for store FQ28 | | BC_COMPANY_FQ88 | No | Company GUID for store FQ88 | | BC_COMPANY_FQFR | No | Company GUID for Franquicias (FQFR) | | LOG_LEVEL | No | debug, info, warn, error (default: info) |

Chart of Accounts

10 expense categories mapped to account ranges 60000-99999:

Planta Fisica (60000-60999) — Rent, utilities
Alquiler Equipos (61000-61999) — Equipment rental
Logistica (62000-62999) — Vehicles, delivery
Marketing (63000-63999) — Advertising, commissions
Administrativos (64000-64999) — Office, software
Seguros (65000-65999) — Insurance
Bancarios (67000-67999) — Banking fees, interest
Servicios Contratados (68000-68999) — Contracted services
Nomina (70000-74999) — Payroll, benefits
Otros (80000-99999) — Depreciation, other

Architecture

mcp-fullqueso-bc-gastos/
├── server.js              # MCP server entry point (22 tools)
├── lib/
│   ├── bc-client.js       # OAuth + BC API (v2.0, OData V4, Beta)
│   ├── expense-analyzer.js
│   ├── ratio-calculator.js
│   ├── anomaly-detector.js
│   ├── trend-analyzer.js
│   └── formatter.js
├── config/
│   ├── expense-accounts.js
│   ├── income-accounts.js
│   ├── benchmarks.js
│   ├── company-config.js
│   └── bank-keywords.js
├── tools/
│   ├── [9 expense/vendor tools]
│   ├── auditoria/         # 7 bank reconciliation tools
│   └── cobranzas/         # 6 AR/AP tools
└── utils/
    ├── date-helper.js
    ├── currency-converter.js
    └── logger.js

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@fullqueso/mcp-bc-gastos

Features

Installation

Claude Desktop

Local Development

Tools (58)

Expense Analysis & Core (11 tools)

compare_stores

detect_anomalies

get_account_transactions

get_crm_rate

get_efficiency_ratios

get_exchange_rate

get_expense_analysis

get_expense_details

get_trends

get_vendor_transactions

list_vendors

Auditoría / POS Reconciliation (11 tools)

find_potential_matches

get_bank_ledger_entries

get_bank_reconciliation_report

get_gl_account_entries

get_pm_receipts

get_reconciliation_status

get_unmatched_ledger_entries

get_unmatched_statement_lines

list_bank_accounts

reconcile_pos_sales

suggest_journal_entries

Cierre Mensual Bancario (6 tools)

generate_closing_journal

get_closing_match_results

get_closing_questionnaire

reconcile_closing_with_bc

start_month_closing

submit_closing_answers

Cobranzas (AR / AP) (7 tools)

get_collection_status

get_customer_balances

get_customer_ledger

get_customer_list

get_open_payables

get_open_receivables

get_vendor_ledger

Financial Statements & Cash Flow (3 tools)

get_cash_flow

get_financial_statements

get_income_statement

Inventario (7 tools)

get_inventory_by_location

get_inventory_change

get_inventory_levels

get_item_card

get_item_cost_analysis

get_item_cost_trend

get_item_ledger_entries

Draft Visibility (Multi-Payments + facturas sin postear) (4 tools)

get_draft_payables

get_draft_receivables

get_draft_summary

get_unposted_invoices

Nómina (3 tools)

get_employees

get_payroll_documents

get_payroll_lines

Reports (2 tools)

generate_cxp_report

generate_manager_report

Ventas (4 tools)

compare_sales_by_store

get_item_sales_detail

get_product_performance

get_sales_analysis