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

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_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 server supports two transport methods:

STDIO Transport (Default)

Standard input/output transport for MCP clients like Claude Desktop:

# Set in .env or environment

ABRAFLEXI_MCP_TRANSPORT=stdio

HTTP Transport

HTTP-based transport for web integrations:

# Set in .env or environment

ABRAFLEXI_MCP_TRANSPORT=streamable-http ABRAFLEXI_MCP_HOST=127.0.0.1 ABRAFLEXI_MCP_PORT=8000 ABRAFLEXI_MCP_STATELESS_HTTP=false AUTH_TYPE=no-auth

Testing

Run test suite:

uv run python scripts/test_server.py

Read-Only Mode

When READ_ONLY=true (default), the server will only expose GET operations (retrieve data) and block all create, update, and delete operations. This is useful for:

• 📊 Monitoring dashboards
• 🔍 Read-only integrations
• 🔒 Security-conscious environments
• 🛡️ Preventing accidental modifications

To enable write operations, set READ_ONLY=false in your .env file.

Example Tool Calls

Get all issued invoices:

invoice_issued_get(limit=10)

Get specific invoice by code:

invoice_issued_get(kod="INV-2024-001")

Count invoices issued in August 2026 (without downloading full records):

invoice_issued_get(

datum_vystaveni_od="2026-08-01", datum_vystaveni_do="2026-08-31", detail="id", add_row_count=True )

Create a new contact:

contact_create(

kod="CUSTOMER01", nazev="Example Company s.r.o.", email="info@example.com", tel="+420123456789" )

Get products:

product_get(nazev="Widget", limit=5)

Generic evidence query (with pagination/sorting):

evidence_get(

evidence="faktura-vydana", filter_expr="datVyst >= '2024-01-01'", order="datVyst", order_direction="D", limit=20, start=0 )