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

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 (22)

Expense Analysis (5 tools)

get_expense_analysis

Detailed expense analysis by category with account-level detail and benchmark comparisons.

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

get_efficiency_ratios

Financial ratios: expense-to-income, payroll, rent, utilities, marketing, operating margin.

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

compare_stores

Compare all stores with efficiency rankings, variances, and savings opportunities.

• Params: period, month, start_date, end_date

detect_anomalies

Detect expense anomalies with severity levels, root causes, and recommended actions.

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

get_trends

Historical trend analysis (up to 6 months) with growth rates, seasonality, and ASCII charts.

• Params: store, months

Drill-Down & Vendors (4 tools)

get_expense_details

Transaction-level drill-down with vendor lookup, category/account filters, and pagination.

• Params: store (req), period, month, start_date, end_date, category, account_number, min_amount, vendor_search, limit, offset

get_account_transactions

Per-account ledger with running balance and vendor information.

• Params: account_number (req), store (req), start_date (req), end_date (req)

get_vendor_transactions

All transactions for a vendor (partial name search) with account breakdown.

• Params: store (req), vendor_search (req), start_date (req), end_date (req)

list_vendors

Directory of active vendors ordered by total amount paid.

• Params: store (req), start_date, end_date

Bank Reconciliation (7 tools)

These tools use OData V4 Web Services. Amounts in VES. Read-only.

list_bank_accounts

List active bank accounts for a store.

• Params: store (req)

get_reconciliation_status

Open reconciliation summary: matched vs unmatched lines per bank account.

• Params: store (req), bank_account

get_unmatched_statement_lines

Bank statement lines not reconciled with BC, categorized by type (payments/deposits).

• Params: store (req), bank_account (req), statement_no, min_amount, type_filter

get_unmatched_ledger_entries

BC ledger entries not cleared at the bank, with stale entry detection (>30 days).

• Params: store (req), bank_account (req), date_from, date_to

find_potential_matches

Scoring-based match finder (0-100) for unmatched bank lines against BC entries.

• Params: store (req), bank_account (req), statement_amount (req), transaction_date (req), description, date_tolerance_days, amount_tolerance_pct

suggest_journal_entries

Suggest GL journal entries for unreconciled bank payments using keyword matching and historical patterns.

• Params: store (req), bank_account (req), statement_no, auto_categorize

reconcile_pos_sales

Multi-bank POS sales reconciliation. Matches bank deposits against BC lot records with commission tracking.

• Banesco: lot-based matching, commission netted in deposit
• Bancrecer: lot-based with separate commission/ISLR lines
• BDV: aggregate matching by period totals (no lot numbers)
• UBII: cross-account matching (BC virtual account → Bancrecer/BDV deposits)
• Params: store (req), start_date (req), end_date (req), bank_account

Accounts Receivable & Payable (6 tools)

These tools use the Finance Reports Beta API. Amounts in VES and USD. Read-only.

get_customer_balances

Customers with outstanding balances.

• Params: store (req), only_with_balance, customer_number

get_customer_ledger

Customer transaction history: invoices, payments, credit memos with collection rate.

• Params: store (req), start_date (req), end_date (req), customer_number, document_type, open_only

get_open_receivables

Open accounts receivable by customer with aging buckets (0-30, 31-60, 61-90, 90+).

• Params: store (req), as_of_date, customer_number, min_amount

get_collection_status

Period collection completeness: "Were all December invoices collected?"

• Params: store (req), start_date (req), end_date (req)

get_vendor_ledger

Vendor transaction history: bills received, payments made.

• Params: store (req), start_date (req), end_date (req), vendor_number, document_type, open_only

get_open_payables

Open accounts payable by vendor with aging buckets (0-30, 31-60, 61-90, 90+).

• Params: store (req), as_of_date, vendor_number, min_amount

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 | | LOG_LEVEL | No | debug, info, warn, error (default: info) |

Chart of Accounts

10 expense categories mapped to account ranges 60000-99999:

1. Planta Fisica (60000-60999) — Rent, utilities
2. Alquiler Equipos (61000-61999) — Equipment rental
3. Logistica (62000-62999) — Vehicles, delivery
4. Marketing (63000-63999) — Advertising, commissions
5. Administrativos (64000-64999) — Office, software
6. Seguros (65000-65999) — Insurance
7. Bancarios (67000-67999) — Banking fees, interest
8. Servicios Contratados (68000-68999) — Contracted services
9. Nomina (70000-74999) — Payroll, benefits
10. 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