Comarch Betterfly MCP Server

Complete integration with the Comarch Betterfly invoicing and accounting system. Manage customers, products, invoices, proformas, and payments through AI.

MCP Protocol 2024-11-05 x-api-key Auth OAuth 2.0 (Betterfly API) 21 Tools

Available Tools

👥

Customers (Kontrahenci)

betterfly_list_customers READ
List customers with OData filtering. Filter by name, NIP, email.
betterfly_get_customer READ
Get customer details by ID.
betterfly_create_customer WRITE
Create a new customer with name, NIP, address, contact info.
betterfly_update_customer WRITE
Update customer data.
betterfly_delete_customer DELETE
Delete a customer by ID.
📦

Products (Produkty)

betterfly_list_products READ
List products with OData filtering.
betterfly_get_product READ
Get product details by ID.
betterfly_create_product WRITE
Create product with name, unit, VAT rate, prices.
betterfly_update_product WRITE
Update product data.
betterfly_delete_product DELETE
Delete a product (not stock-controlled ones).
🧾

Sales Invoices (Faktury sprzedazy)

betterfly_list_invoices READ
List sales invoices with OData filtering.
betterfly_get_invoice READ
Get invoice details by ID.
betterfly_create_invoice WRITE
Create invoice (enters buffer, needs confirmation).
betterfly_update_invoice WRITE
Update buffered invoice. Warning: omitted fields are zeroed.
betterfly_confirm_invoices WRITE
Confirm and number invoices from buffer.
betterfly_delete_invoice DELETE
Delete buffered invoice only.
📄

Purchase Invoices, Proformas & Payments

betterfly_list_purchase_invoices READ
List purchase invoices.
betterfly_get_purchase_invoice READ
Get purchase invoice by ID.
betterfly_list_proformas READ
List proforma invoices.
betterfly_get_proforma READ
Get proforma details by ID.
betterfly_create_proforma WRITE
Create proforma (quote/estimate).
betterfly_list_payment_types READ
List available payment methods.
betterfly_list_bank_accounts READ
List configured bank accounts.

Setup

Claude Code (HTTP)

Add to your Claude Code MCP configuration:

{
  "mcpServers": {
    "comarch-betterfly": {
      "type": "http",
      "url": "https://comarch-betterfly.mcp.majewscy.tech",
      "headers": {
        "x-api-key": "YOUR_API_KEY"
      }
    }
  }
}

Prerequisites

To use this MCP server, you need Comarch Betterfly API credentials:

  1. Log in to your Comarch Betterfly account
  2. Navigate to: Moje konto → Zarzadzaj kontem → Public API
  3. Generate an API key pair (Client ID + Client Secret)
  4. Configure the server with your credentials

API Reference

Authentication

All MCP requests require the x-api-key header for server authentication. The Betterfly API uses OAuth 2.0 client credentials flow with automatic token refresh.

VAT Rate Codes

Comarch Betterfly uses numeric codes, NOT percentages:

9 = 23% (standard rate)
8 = 8%  (food & agricultural goods)
7 = 5%  (books, art)
6 = 4%  (specific items)
2 = 0%  (zero rate)
1 = Zwolniony (exempt)
0 = Nie dotyczy (not applicable)

Invoice Workflow

Invoices follow a buffer-confirmation workflow:

  1. Create — invoice enters buffer (Status=0, editable, no number)
  2. Edit — modify while in buffer (all fields must be provided)
  3. Confirm — assigns official number, locks for editing (Status=1)
  4. Delete — only possible while in buffer

Health Check

GET /health
Response: { "status": "ok", "serverType": "comarch-betterfly-mcp", ... }