AbraFlexi
MCP server for AbraFlexi ERP β invoices, contacts, products, bank transactions.
Ask AI about AbraFlexi
Powered by Claude Β· Grounded in docs
I know everything about AbraFlexi. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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
π Invoice Management
invoice_issued_get- Retrieve issued invoices (faktura-vydana)invoice_issued_create- Create new issued invoicesinvoice_issued_update- Update existing issued invoicesinvoice_issued_delete- Remove issued invoicesinvoice_received_get- Retrieve received invoices (faktura-prijata)invoice_received_create- Create new received invoices
π₯ Contact Management
contact_get- Retrieve contacts and companies (adresar)contact_create- Create new contactscontact_update- Update existing contactscontact_delete- Remove contacts
π¦ Product Management
product_get- Retrieve products from price list (cenik)product_create- Create new productsproduct_update- Update existing productsproduct_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 evidenceevidence_create- Create record in any evidenceevidence_update- Update record in any evidenceevidence_delete- Delete record from any evidenceevidence_list- List all available evidences
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
-
Clone the repository:
git clone https://github.com/VitexSoftware/abraflexi-mcp-server.git cd abraflexi-mcp-server -
Install with uv (recommended):
uv sync uv run python scripts/start_server.pyOr 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 usernameABRAFLEXI_PASSWORD- Your AbraFlexi password
Method 2: Session ID
ABRAFLEXI_AUTHSESSID- Your AbraFlexi session ID
Optional Configuration
READ_ONLY- Set totrue,1, oryesto enable read-only mode (default:true)ABRAFLEXI_TIMEOUT- Request timeout in seconds (default:300)
Transport Configuration
ABRAFLEXI_MCP_TRANSPORT- Transport type:stdio(default) orstreamable-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 tono-authfor 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
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:
evidence_get(
evidence="faktura-vydana",
filter_expr="datVyst >= '2024-01-01'",
limit=20
)
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
βββ 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
.envfile (never commit to git) - π Enable read-only mode for monitoring-only use cases
- π‘οΈ Use HTTPS for AbraFlexi server connections
- π Regularly rotate passwords
- π Ensure
.envfile has proper permissions (600)
Troubleshooting
Common Issues
Connection Failed:
- Verify
ABRAFLEXI_URLis 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
- FastMCP - MCP server framework
- python-abraflexi - AbraFlexi Python library
- python-dotenv - Environment variable management
License
This project is licensed under the MIT License.
Acknowledgments
- AbraFlexi for the accounting platform
- Model Context Protocol for the integration standard
- FastMCP for the server framework
Support
- π Documentation
- π Issue Tracker
- π¬ AbraFlexi API Documentation
Author
VΓtΔzslav DvoΕΓ‘k
- Email: info@vitexsoftware.cz
- GitHub: @VitexSoftware
Made with β€οΈ for the AbraFlexi and MCP communities
