AbraFlexi

AbraFlexi MCP Server

A comprehensive Model Context Protocol (MCP) server for AbraFlexi integration using FastMCP and python-abraflexi. This server provides complete access to AbraFlexi REST API functionality through MCP-compatible tools.

Features

69 tools in total, covering the full REST surface exposed by python-abraflexi: dedicated tools for the most common evidences (invoices, contacts, products, bank transactions), plus generic evidence_* tools that work against *any* AbraFlexi evidence by name.

One server process = one AbraFlexi company. A running server is bound

for its whole lifetime to a single company, set via

ABRAFLEXI_URL/ABRAFLEXI_COMPANY (see Configuration).

Every record any tool returns already belongs to that company - it is not

possible to ask this server for another company's data. Call server_info

to check which company/URL a running server is bound to; the main

record-fetching tools (invoice_issued_get, invoice_received_get,

contact_get, product_get, bank_transaction_get, evidence_get,

changes_get) also echo it back in a _context block on every response,

together with a note clarifying any counterparty fields on the records

(e.g. an invoice's nazFirmy is the customer/supplier, not the company

that issued/received it).

ℹ️ Server Identity

• server_info - Report which AbraFlexi company/URL this server session is bound to

📄 Invoice Management

• invoice_issued_get - Retrieve issued invoices (faktura-vydana)
• invoice_issued_create - Create new issued invoices
• invoice_issued_update - Update existing issued invoices
• invoice_issued_delete - Remove issued invoices
• invoice_received_get - Retrieve received invoices (faktura-prijata)
• invoice_received_create - Create new received invoices

💳 Issued Invoice Business Logic

• invoice_issued_match_payment - Match an invoice against a payment document (Párování plateb)
• invoice_issued_cash_payment - Pay an invoice in cash (Hotovostní úhrada)
• invoice_issued_deduct_advance - Deduct an advance invoice (Odpočet záloh a ZDD)
• invoice_issued_deduct_zdd - Deduct an advance tax document, ZDD (Odpočet záloh a ZDD)
• invoice_issued_link_zdd - Link a ZDD to an income payment (Vazby ZDD)
• invoice_issued_unlink_zdd - Remove a ZDD bonding (Vazby ZDD)
• invoice_issued_overdue_days - Compute days overdue from a due date (pure, no API call)
• invoice_issued_get_email - Resolve the best recipient email for an invoice
• invoice_issued_get_recipients - Resolve all recipient emails for an invoice

🏢 Company Management

• company_create - Found a brand-new AbraFlexi company (accounting unit) - requires server-admin/license REST rights

👥 Contact Management

• contact_get - Retrieve contacts and companies (adresar)
• contact_create - Create new contacts
• contact_update - Update existing contacts
• contact_delete - Remove contacts

☎️ Contact Convenience Lookups

• contact_get_notification_email - Best email to notify (primary/purpose-matching contact)
• contact_get_cell_phone - Cell phone number to use
• contact_get_any_phone - Any usable phone number (mobile preferred over landline)
• contact_get_bank_accounts - Registered bank account(s) for a contact

📦 Product Management

• product_get - Retrieve products from price list (cenik)
• product_create - Create new products
• product_update - Update existing products
• product_delete - Remove products

🏦 Bank Transaction Management

• bank_transaction_get - Retrieve bank transactions (banka)
• bank_transaction_create - Create new bank transactions

🔧 Generic Evidence Operations

• evidence_get - Get records from any evidence (filter, pagination, sorting, relations)
• evidence_create - Create record in any evidence
• evidence_update - Update record in any evidence (supports remove_external_ids)
• evidence_delete - Delete record from any evidence
• evidence_list - List all evidences available on the bound company (live evidence-list.json)

🧠 Python-abraflexi Bridge

• abraflexi_client_methods - List public methods of core python-abraflexi clients (ReadOnly, ReadWrite, Changes, Adresar, FakturaVydana)
• abraflexi_client_call - Invoke a selected public client method with arguments (write methods still respect READ_ONLY)

🔒 Locking, Actions & Batch Operations

• evidence_lock / evidence_unlock / evidence_lock_for_ucetni - Lock/unlock a record
• evidence_storno - Cancel (storno) a document record
• evidence_perform_action - Call a record's dedicated business action (e.g. pay)
• evidence_mass_update - Update, or act on, every record matching a filter (Dávkové operace)
• evidence_batch_insert / evidence_batch_update - Insert/update many records in one request

📎 Attachments

• evidence_attach_file - Attach a local file to any record
• evidence_list_attachments - List a record's attachments
• evidence_get_attachment - Get metadata for a single attachment
• evidence_download_attachment - Download an attachment to a local file
• evidence_get_attachment_thumbnail - Download an image attachment's thumbnail
• evidence_delete_attachment - Delete an attachment

🧾 Reports, QR Codes & User Queries

• evidence_export_report - Export a PDF/XLSX report for a record or evidence listing
• evidence_get_qr_code - Get a document's payment QR code (file or base64 data URI)
• user_query_list - List saved user-defined queries (uzivatelsky-dotaz)
• call_user_query - Call a saved user-defined query (uživatelský dotaz)

ℹ️ Evidence Metadata & Summation

• evidence_get_properties - List the fields supported by an evidence
• evidence_get_reports - List the printable reports available for an evidence
• evidence_get_relations_list - List the sub-evidences (relations) available for an evidence
• evidence_get_sum - Get summation (totals) for an evidence
• evidence_get_record_changes - Get a single record's change history

🏷️ Labels (štítky)

• evidence_get_labels - Get labels assigned to a record
• evidence_set_label - Add a label
• evidence_unset_label - Remove specific label(s)
• evidence_unset_labels - Remove all labels

🔄 Changes API (company-wide incremental sync)

• changes_enable / changes_disable - Toggle change tracking
• changes_status - Check whether change tracking is enabled
• changes_get - Page through recorded changes since a given version

🪝 Web Hooks (push notifications about changes)

AbraFlexi POSTs the changes since the previous call to every registered hook URL (same body as the Changes API, usually within seconds, not counted towards the API request limit). Hooks need the Changes API enabled for the company (changes_enable) and, on self-hosted servers, enableHooks=true in flexibee-server.xml. A hook cannot be filtered by evidence: the receiver gets every change. See the AbraFlexi API docs, *Web Hooks*.

Write tools respect READ_ONLY (default true). A hook delivers every change of the company to its receiver, so set ABRAFLEXI_WEBHOOK_ALLOWED_HOSTS (comma-separated host names, *.example.com allowed) to restrict where webhook_register may point hooks; when unset any http(s) host is accepted. sec_key is sent to AbraFlexi as the X-FB-Hook-SecKey secret and is masked in every tool response and error message. Only absolute http(s) URLs without embedded credentials are accepted.

Installation

Prerequisites

• Python 3.10 or higher
• Access to an AbraFlexi server with API enabled

Option 1: Install from PyPI (Recommended)

pip install abraflexi-mcp-server

Then run the server:

abraflexi-mcp

Option 2: AppImage (Linux)

Download the self-contained AppImage from the latest release:

chmod +x AbraFlexi-MCP-Server-*-x86_64.AppImage

./AbraFlexi-MCP-Server-*-x86_64.AppImage

No Python or pip required. See AppImage section for details.

Option 3: Install from Source

1. Clone the repository:

   git clone https://github.com/VitexSoftware/abraflexi-mcp-server.git

cd abraflexi-mcp-server

1. Install with uv (recommended):

   uv sync

uv run python scripts/start_server.py

Or with pip:

   pip install -e .

abraflexi-mcp

Cloud Deployment

A testing deployment is available at:

🌐 https://abraflexi.fastmcp.app/mcp

This cloud-hosted instance allows you to test and use the AbraFlexi MCP server without local installation. Configure your MCP client to connect to this endpoint with HTTP transport.

Note: This is a testing deployment. For production use, we recommend self-hosting using one of the installation methods above.

Configuration

Create a .env file or set environment variables:

cp .env.example .env

Edit .env with your AbraFlexi server details

Configuration

Required Environment Variables

• ABRAFLEXI_URL - Your AbraFlexi server URL (e.g., https://demo.flexibee.eu:5434)
• ABRAFLEXI_COMPANY - Company identifier (e.g., demo_de)

Authentication (choose one method)

Method 1: Username/Password (Recommended)

• ABRAFLEXI_LOGIN - Your AbraFlexi username
• ABRAFLEXI_PASSWORD - Your AbraFlexi password

Method 2: Session ID

• ABRAFLEXI_AUTHSESSID - Your AbraFlexi session ID

Optional Configuration

• READ_ONLY - Set to true, 1, or yes to enable read-only mode (default: true)
• ABRAFLEXI_WEBHOOK_ALLOWED_HOSTS - Optional comma-separated allowlist of host names webhook_register may use as hook receivers, e.g. multiflexi.vitexsoftware.com,*.spoje.net (default: unrestricted)
• ABRAFLEXI_TIMEOUT - Request timeout in seconds (default: 300)

Transport Configuration

• ABRAFLEXI_MCP_TRANSPORT - Transport type: stdio (default) or streamable-http

HTTP Transport Configuration (only used when ABRAFLEXI_MCP_TRANSPORT=streamable-http):

• ABRAFLEXI_MCP_HOST - Server host (default: 127.0.0.1)
• ABRAFLEXI_MCP_PORT - Server port (default: 8000)
• ABRAFLEXI_MCP_STATELESS_HTTP - Stateless mode (default: false)
• AUTH_TYPE - Must be set to no-auth for streamable-http transport

Usage

Running the Server

With startup script (recommended):

uv run python scripts/start_server.py

Direct execution:

uv run python -m abraflexi_mcp_server.server

CLI help:

abraflexi-mcp --help

Transport Options

The