Skip to content

VitexSoftware/abraflexi-mcp-server

BranchesTags

Repository files navigation

AbraFlexi MCP Server

AbraFlexi MCP Server icon

License: MIT Python 3.10+ PyPI version

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

64 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.

📄 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

👥 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 available evidences

🔒 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)
  • 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

  2. 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")

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
)

Attach a local file to any record:

evidence_attach_file(evidence="cenik", kod="PRODUCT01", filepath="/path/to/photo.jpg")

Lock an invoice, then export its PDF:

evidence_lock(evidence="faktura-vydana", kod="INV-2024-001")
evidence_export_report(
    evidence="faktura-vydana",
    kod="INV-2024-001",
    output_path="/tmp/invoice.pdf",
    report_name="dodaciList"
)

Mass-update every price-list item from a supplier:

evidence_mass_update(
    evidence="cenik",
    filter_expr="dodavatel = 'code:SUPPLIER01'",
    data={"stitky": "code:VIP"}
)

Incremental sync via the Changes API:

changes_enable()
page = changes_get(start=0, limit=500, evidences=["faktura-vydana"])
# page["changes"], page["next"], page["global_version"]

MCP Integration

This server is designed to work with MCP-compatible clients like Claude Desktop. See MCP_SETUP.md for detailed integration instructions.

OCI Container

The server can be run as an OCI container (Docker/Podman) — no Python installation needed on the host.

Building the image

podman build -t abraflexi-mcp-server -f Containerfile .

Running the container

The image defaults to streamable-http transport on port 8000.

With individual environment variables:

podman run --rm -p 8000:8000 \
  -e ABRAFLEXI_URL=https://demo.flexibee.eu:5434 \
  -e ABRAFLEXI_COMPANY=demo_de \
  -e ABRAFLEXI_LOGIN=winstrom \
  -e ABRAFLEXI_PASSWORD=winstrom \
  abraflexi-mcp-server

With an env file:

podman run --rm -p 8000:8000 --env-file .env abraflexi-mcp-server

Container environment defaults

Variable Default
ABRAFLEXI_MCP_TRANSPORT streamable-http
ABRAFLEXI_MCP_HOST 0.0.0.0
ABRAFLEXI_MCP_PORT 8000
READ_ONLY true

All other configuration variables can be passed as environment variables.

AppImage

A self-contained, single-file Linux executable — no Python, pip, or any other dependency required on the host.

Building the AppImage

bash appimage/build-appimage.sh

The script downloads a portable CPython and appimagetool automatically. The resulting file is placed in build/appimage/:

build/appimage/AbraFlexi-MCP-Server-<version>-x86_64.AppImage

Running the AppImage

The AppImage automatically loads a .env file from the current working directory if one is present.

With a .env file (recommended):

cp .env.example .env
# edit .env with your credentials
./AbraFlexi-MCP-Server-*-x86_64.AppImage

With inline environment variables:

ABRAFLEXI_URL=https://demo.flexibee.eu:5434 \
ABRAFLEXI_COMPANY=demo_de \
ABRAFLEXI_LOGIN=winstrom \
ABRAFLEXI_PASSWORD=winstrom \
./AbraFlexi-MCP-Server-*-x86_64.AppImage

Development

Project Structure

abraflexi-mcp-server/
├── abraflexi_mcp_server/
│   ├── __init__.py
│   └── server.py                  # Main server implementation
├── appimage/
│   ├── AppRun                     # AppImage entry point
│   ├── abraflexi-mcp-server.desktop
│   ├── abraflexi-mcp-server.svg
│   └── build-appimage.sh          # AppImage build script
├── debian/                        # Debian packaging
│   ├── abraflexi-mcp-server.svg   # AppStream stock icon
│   ├── abraflexi-mcp-server.install
│   └── cz.vitexsoftware.abraflexi-mcp-server.metainfo.xml
├── scripts/
│   ├── start_server.py            # Startup script with validation
│   └── test_server.py             # Test script
├── Containerfile                  # OCI container build
├── server.json                    # MCP Registry manifest
├── pyproject.toml                 # Python project configuration
├── setup.py                       # Legacy setuptools configuration
├── requirements.txt               # Dependencies
├── .env.example                   # Environment configuration template
├── .env                           # Your configuration (not in git)
├── .gitignore                     # Git ignore patterns
└── README.md                      # This file

Running Tests

# Test server functionality
uv run python scripts/test_server.py

# Test with specific environment
ABRAFLEXI_URL=https://your-server.com uv run python scripts/test_server.py

Error Handling

The server includes comprehensive error handling:

  • ✅ Authentication errors are clearly reported
  • 🔒 Read-only mode violations are blocked with descriptive messages
  • ✔️ Invalid parameters are validated
  • 🌐 Network and API errors are properly formatted
  • 📝 Detailed logging for troubleshooting

Security Considerations

  • 🔑 Store credentials securely in .env file (never commit to git)
  • 🔒 Enable read-only mode for monitoring-only use cases
  • 🛡️ Use HTTPS for AbraFlexi server connections
  • 🔄 Regularly rotate passwords
  • 📁 Ensure .env file has proper permissions (600)

Troubleshooting

Common Issues

Connection Failed:

  • Verify ABRAFLEXI_URL is correct and accessible
  • Check authentication credentials
  • Ensure AbraFlexi API is enabled
  • Check firewall/network settings

Permission Denied:

  • Verify user has sufficient AbraFlexi permissions
  • Check if read-only mode is enabled when trying to modify data

Tool Not Found:

  • Ensure all dependencies are installed: uv sync
  • Verify Python version compatibility (3.10+)

Debug Mode

Set environment variable for detailed logging:

export DEBUG=1
uv run python scripts/start_server.py

Dependencies

License

This project is licensed under the MIT License.

Acknowledgments

Support

Author

Vítězslav Dvořák

Made with ❤️ for the AbraFlexi and MCP communities

About

MCP server for AbraFlexi integration using FastMCP and python-abraflexi

Resources

Readme
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 2

v1.0.2 Latest
Jun 30, 2026
+ 1 release

Packages

 
 
 

Contributors

Languages