{
  "markdown": "# AbraFlexi MCP Server\n\n<img src=\"debian/abraflexi-mcp-server.svg\" alt=\"AbraFlexi MCP Server icon\" width=\"96\" height=\"96\">\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\n[![PyPI version](https://badge.fury.io/py/abraflexi-mcp-server.svg)](https://badge.fury.io/py/abraflexi-mcp-server)\n![Packaging: deb](https://img.shields.io/badge/packaging-.deb-red?logo=debian&logoColor=white)\n[![M8ven Score](https://m8ven.ai/badge/mcp/vitexsoftware-abraflexi-mcp-server-jhy0dc)](https://m8ven.ai/mcp/vitexsoftware-abraflexi-mcp-server-jhy0dc)\n\nA 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.\n\n## Features\n\n68 tools in total, covering the full REST surface exposed by\n[python-abraflexi](https://github.com/VitexSoftware/python-abraflexi):\ndedicated tools for the most common evidences (invoices, contacts,\nproducts, bank transactions), plus generic `evidence_*` tools that work\nagainst *any* AbraFlexi evidence by name.\n\n> **One server process = one AbraFlexi company.** A running server is bound\n> for its whole lifetime to a single company, set via\n> `ABRAFLEXI_URL`/`ABRAFLEXI_COMPANY` (see [Configuration](#configuration)).\n> Every record any tool returns already belongs to that company - it is not\n> possible to ask this server for another company's data. Call `server_info`\n> to check which company/URL a running server is bound to; the main\n> record-fetching tools (`invoice_issued_get`, `invoice_received_get`,\n> `contact_get`, `product_get`, `bank_transaction_get`, `evidence_get`,\n> `changes_get`) also echo it back in a `_context` block on every response,\n> together with a note clarifying any counterparty fields on the records\n> (e.g. an invoice's `nazFirmy` is the customer/supplier, not the company\n> that issued/received it).\n\n### ℹ️ Server Identity\n- `server_info` - Report which AbraFlexi company/URL this server session is bound to\n\n### 📄 Invoice Management\n- `invoice_issued_get` - Retrieve issued invoices (faktura-vydana)\n- `invoice_issued_create` - Create new issued invoices\n- `invoice_issued_update` - Update existing issued invoices\n- `invoice_issued_delete` - Remove issued invoices\n- `invoice_received_get` - Retrieve received invoices (faktura-prijata)\n- `invoice_received_create` - Create new received invoices\n\n### 💳 Issued Invoice Business Logic\n- `invoice_issued_match_payment` - Match an invoice against a payment document (Párování plateb)\n- `invoice_issued_cash_payment` - Pay an invoice in cash (Hotovostní úhrada)\n- `invoice_issued_deduct_advance` - Deduct an advance invoice (Odpočet záloh a ZDD)\n- `invoice_issued_deduct_zdd` - Deduct an advance tax document, ZDD (Odpočet záloh a ZDD)\n- `invoice_issued_link_zdd` - Link a ZDD to an income payment (Vazby ZDD)\n- `invoice_issued_unlink_zdd` - Remove a ZDD bonding (Vazby ZDD)\n- `invoice_issued_overdue_days` - Compute days overdue from a due date (pure, no API call)\n- `invoice_issued_get_email` - Resolve the best recipient email for an invoice\n- `invoice_issued_get_recipients` - Resolve all recipient emails for an invoice\n\n### 🏢 Company Management\n- `company_create` - Found a brand-new AbraFlexi company (accounting unit) - requires server-admin/license REST rights\n\n### 👥 Contact Management\n- `contact_get` - Retrieve contacts and companies (adresar)\n- `contact_create` - Create new contacts\n- `contact_update` - Update existing contacts\n- `contact_delete` - Remove contacts\n\n### ☎️ Contact Convenience Lookups\n- `contact_get_notification_email` - Best email to notify (primary/purpose-matching contact)\n- `contact_get_cell_phone` - Cell phone number to use\n- `contact_get_any_phone` - Any usable phone number (mobile preferred over landline)\n- `contact_get_bank_accounts` - Registered bank account(s) for a contact\n\n### 📦 Product Management\n- `product_get` - Retrieve products from price list (cenik)\n- `product_create` - Create new products\n- `product_update` - Update existing products\n- `product_delete` - Remove products\n\n### 🏦 Bank Transaction Management\n- `bank_transaction_get` - Retrieve bank transactions (banka)\n- `bank_transaction_create` - Create new bank transactions\n\n### 🔧 Generic Evidence Operations\n- `evidence_get` - Get records from any evidence (filter, pagination, sorting, relations)\n- `evidence_create` - Create record in any evidence\n- `evidence_update` - Update record in any evidence (supports `remove_external_ids`)\n- `evidence_delete` - Delete record from any evidence\n- `evidence_list` - List all available evidences\n\n### 🧠 Python-abraflexi Bridge\n- `abraflexi_client_methods` - List public methods of core python-abraflexi clients (`ReadOnly`, `ReadWrite`, `Changes`, `Adresar`, `FakturaVydana`)\n- `abraflexi_client_call` - Invoke a selected public client method with arguments (write methods still respect `READ_ONLY`)\n\n### 🔒 Locking, Actions & Batch Operations\n- `evidence_lock` / `evidence_unlock` / `evidence_lock_for_ucetni` - Lock/unlock a record\n- `evidence_storno` - Cancel (storno) a document record\n- `evidence_perform_action` - Call a record's dedicated business action (e.g. `pay`)\n- `evidence_mass_update` - Update, or act on, every record matching a filter (Dávkové operace)\n- `evidence_batch_insert` / `evidence_batch_update` - Insert/update many records in one request\n\n### 📎 Attachments\n- `evidence_attach_file` - Attach a local file to any record\n- `evidence_list_attachments` - List a record's attachments\n- `evidence_get_attachment` - Get metadata for a single attachment\n- `evidence_download_attachment` - Download an attachment to a local file\n- `evidence_get_attachment_thumbnail` - Download an image attachment's thumbnail\n- `evidence_delete_attachment` - Delete an attachment\n\n### 🧾 Reports, QR Codes & User Queries\n- `evidence_export_report` - Export a PDF/XLSX report for a record or evidence listing\n- `evidence_get_qr_code` - Get a document's payment QR code (file or base64 data URI)\n- `call_user_query` - Call a saved user-defined query (uživatelský dotaz)\n\n### ℹ️ Evidence Metadata & Summation\n- `evidence_get_properties` - List the fields supported by an evidence\n- `evidence_get_reports` - List the printable reports available for an evidence\n- `evidence_get_relations_list` - List the sub-evidences (relations) available for an evidence\n- `evidence_get_sum` - Get summation (totals) for an evidence\n- `evidence_get_record_changes` - Get a single record's change history\n\n### 🏷️ Labels (štítky)\n- `evidence_get_labels` - Get labels assigned to a record\n- `evidence_set_label` - Add a label\n- `evidence_unset_label` - Remove specific label(s)\n- `evidence_unset_labels` - Remove all labels\n\n### 🔄 Changes API (company-wide incremental sync)\n- `changes_enable` / `changes_disable` - Toggle change tracking\n- `changes_status` - Check whether change tracking is enabled\n- `changes_get` - Page through recorded changes since a given version\n\n## Installation\n\n### Prerequisites\n\n- Python 3.10 or higher\n- Access to an AbraFlexi server with API enabled\n\n### Option 1: Install from PyPI (Recommended)\n\n```bash\npip install abraflexi-mcp-server\n```\n\nThen run the server:\n```bash\nabraflexi-mcp\n```\n\n### Option 2: AppImage (Linux)\n\nDownload the self-contained AppImage from the\n[latest release](https://github.com/VitexSoftware/abraflexi-mcp-server/releases/latest):\n\n```bash\nchmod +x AbraFlexi-MCP-Server-*-x86_64.AppImage\n./AbraFlexi-MCP-Server-*-x86_64.AppImage\n```\n\nNo Python or pip required. See [AppImage](#appimage) section for details.\n\n### Option 3: Install from Source\n\n1. **Clone the repository:**\n   ```bash\n   git clone https://github.com/VitexSoftware/abraflexi-mcp-server.git\n   cd abraflexi-mcp-server\n   ```\n\n2. **Install with uv (recommended):**\n   ```bash\n   uv sync\n   uv run python scripts/start_server.py\n   ```\n   \n   Or with pip:\n   ```bash\n   pip install -e .\n   abraflexi-mcp\n   ```\n\n## Cloud Deployment\n\nA testing deployment is available at:\n\n**🌐 https://abraflexi.fastmcp.app/mcp**\n\nThis 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.\n\n**Note:** This is a testing deployment. For production use, we recommend self-hosting using one of the installation methods above.\n\n### Configuration\n\nCreate a `.env` file or set environment variables:\n```bash\ncp .env.example .env\n# Edit .env with your AbraFlexi server details\n```\n\n## Configuration\n\n### Required Environment Variables\n\n- `ABRAFLEXI_URL` - Your AbraFlexi server URL (e.g., `https://demo.flexibee.eu:5434`)\n- `ABRAFLEXI_COMPANY` - Company identifier (e.g., `demo_de`)\n\n### Authentication (choose one method)\n\n**Method 1: Username/Password (Recommended)**\n- `ABRAFLEXI_LOGIN` - Your AbraFlexi username\n- `ABRAFLEXI_PASSWORD` - Your AbraFlexi password\n\n**Method 2: Session ID**\n- `ABRAFLEXI_AUTHSESSID` - Your AbraFlexi session ID\n\n### Optional Configuration\n\n- `READ_ONLY` - Set to `true`, `1`, or `yes` to enable read-only mode (default: `true`)\n- `ABRAFLEXI_TIMEOUT` - Request timeout in seconds (default: `300`)\n\n### Transport Configuration\n\n- `ABRAFLEXI_MCP_TRANSPORT` - Transport type: `stdio` (default) or `streamable-http`\n\n**HTTP Transport Configuration** (only used when `ABRAFLEXI_MCP_TRANSPORT=streamable-http`):\n- `ABRAFLEXI_MCP_HOST` - Server host (default: `127.0.0.1`)\n- `ABRAFLEXI_MCP_PORT` - Server port (default: `8000`)\n- `ABRAFLEXI_MCP_STATELESS_HTTP` - Stateless mode (default: `false`)\n- `AUTH_TYPE` - Must be set to `no-auth` for streamable-http transport\n\n## Usage\n\n### Running the Server\n\n**With startup script (recommended):**\n```bash\nuv run python scripts/start_server.py\n```\n\n**Direct execution:**\n```bash\nuv run python -m abraflexi_mcp_server.server\n```\n\n**CLI help:**\n```bash\nabraflexi-mcp --help\n```\n\n### Transport Options\n\nThe server supports two transport methods:\n\n#### STDIO Transport (Default)\nStandard input/output transport for MCP clients like Claude Desktop:\n```bash\n# Set in .env or environment\nABRAFLEXI_MCP_TRANSPORT=stdio\n```\n\n#### HTTP Transport\nHTTP-based transport for web integrations:\n```bash\n# Set in .env or environment\nABRAFLEXI_MCP_TRANSPORT=streamable-http\nABRAFLEXI_MCP_HOST=127.0.0.1\nABRAFLEXI_MCP_PORT=8000\nABRAFLEXI_MCP_STATELESS_HTTP=false\nAUTH_TYPE=no-auth\n```\n\n### Testing\n\n**Run test suite:**\n```bash\nuv run python scripts/test_server.py\n```\n\n### Read-Only Mode\n\nWhen `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:\n\n- 📊 Monitoring dashboards\n- 🔍 Read-only integrations\n- 🔒 Security-conscious environments\n- 🛡️ Preventing accidental modifications\n\nTo enable write operations, set `READ_ONLY=false` in your `.env` file.\n\n### Example Tool Calls\n\n**Get all issued invoices:**\n```python\ninvoice_issued_get(limit=10)\n```\n\n**Get specific invoice by code:**\n```python\ninvoice_issued_get(kod=\"INV-2024-001\")\n```\n\n**Count invoices issued in August 2026 (without downloading full records):**\n```python\ninvoice_issued_get(\n    datum_vystaveni_od=\"2026-08-01\",\n    datum_vystaveni_do=\"2026-08-31\",\n    detail=\"id\",\n    add_row_count=True\n)\n```\n\n**Create a new contact:**\n```python\ncontact_create(\n    kod=\"CUSTOMER01\",\n    nazev=\"Example Company s.r.o.\",\n    email=\"info@example.com\",\n    tel=\"+420123456789\"\n)\n```\n\n**Get products:**\n```python\nproduct_get(nazev=\"Widget\", limit=5)\n```\n\n**Generic evidence query (with pagination/sorting):**\n```python\nevidence_get(\n    evidence=\"faktura-vydana\",\n    filter_expr=\"datVyst >= '2024-01-01'\",\n    order=\"datVyst\",\n    order_direction=\"D\",\n    limit=20,\n    start=0\n)\n```\n\n**Attach a local file to any record:**\n```python\nevidence_attach_file(evidence=\"cenik\", kod=\"PRODUCT01\", filepath=\"/path/to/photo.jpg\")\n```\n\n**Lock an invoice, then export its PDF:**\n```python\nevidence_lock(evidence=\"faktura-vydana\", kod=\"INV-2024-001\")\nevidence_export_report(\n    evidence=\"faktura-vydana\",\n    kod=\"INV-2024-001\",\n    output_path=\"/tmp/invoice.pdf\",\n    report_name=\"dodaciList\"\n)\n```\n\n**Mass-update every price-list item from a supplier:**\n```python\nevidence_mass_update(\n    evidence=\"cenik\",\n    filter_expr=\"dodavatel = 'code:SUPPLIER01'\",\n    data={\"stitky\": \"code:VIP\"}\n)\n```\n\n**Incremental sync via the Changes API:**\n```python\nchanges_enable()\npage = changes_get(start=0, limit=500, evidences=[\"faktura-vydana\"])\n# page[\"changes\"], page[\"next\"], page[\"global_version\"]\n```\n\n## MCP Integration\n\nThis server is designed to work with MCP-compatible clients like Claude Desktop. See [MCP_SETUP.md](MCP_SETUP.md) for detailed integration instructions.\n\n## OCI Container\n\nThe server can be run as an OCI container (Docker/Podman) — no Python installation needed on the host.\n\n### Building the image\n\n```bash\npodman build -t abraflexi-mcp-server -f Containerfile .\n```\n\n### Running the container\n\nThe image defaults to `streamable-http` transport on port **8000**.\n\n**With individual environment variables:**\n```bash\npodman run --rm -p 8000:8000 \\\n  -e ABRAFLEXI_URL=https://demo.flexibee.eu:5434 \\\n  -e ABRAFLEXI_COMPANY=demo_de \\\n  -e ABRAFLEXI_LOGIN=winstrom \\\n  -e ABRAFLEXI_PASSWORD=winstrom \\\n  abraflexi-mcp-server\n```\n\n**With an env file:**\n```bash\npodman run --rm -p 8000:8000 --env-file .env abraflexi-mcp-server\n```\n\n### Container environment defaults\n\n| Variable | Default |\n|---|---|\n| `ABRAFLEXI_MCP_TRANSPORT` | `streamable-http` |\n| `ABRAFLEXI_MCP_HOST` | `0.0.0.0` |\n| `ABRAFLEXI_MCP_PORT` | `8000` |\n| `READ_ONLY` | `true` |\n\nAll other [configuration variables](#configuration) can be passed as environment variables.\n\n## AppImage\n\nA self-contained, single-file Linux executable — no Python, pip, or any other dependency required on the host.\n\n### Building the AppImage\n\n```bash\nbash appimage/build-appimage.sh\n```\n\nThe script downloads a portable CPython and `appimagetool` automatically. The resulting file is placed in `build/appimage/`:\n\n```\nbuild/appimage/AbraFlexi-MCP-Server-<version>-x86_64.AppImage\n```\n\n### Running the AppImage\n\nThe AppImage automatically loads a `.env` file from the current working directory if one is present.\n\n**With a .env file (recommended):**\n```bash\ncp .env.example .env\n# edit .env with your credentials\n./AbraFlexi-MCP-Server-*-x86_64.AppImage\n```\n\n**With inline environment variables:**\n```bash\nABRAFLEXI_URL=https://demo.flexibee.eu:5434 \\\nABRAFLEXI_COMPANY=demo_de \\\nABRAFLEXI_LOGIN=winstrom \\\nABRAFLEXI_PASSWORD=winstrom \\\n./AbraFlexi-MCP-Server-*-x86_64.AppImage\n```\n\n## Development\n\n### Project Structure\n\n```\nabraflexi-mcp-server/\n├── abraflexi_mcp_server/\n│   ├── __init__.py\n│   └── server.py                  # Main server implementation\n├── appimage/\n│   ├── AppRun                     # AppImage entry point\n│   ├── abraflexi-mcp-server.desktop\n│   ├── abraflexi-mcp-server.svg\n│   └── build-appimage.sh          # AppImage build script\n├── debian/                        # Debian packaging\n│   ├── abraflexi-mcp-server.svg   # AppStream stock icon\n│   ├── abraflexi-mcp-server.install\n│   └── cz.vitexsoftware.abraflexi-mcp-server.metainfo.xml\n├── scripts/\n│   ├── start_server.py            # Startup script with validation\n│   └── test_server.py             # Test script\n├── Containerfile                  # OCI container build\n├── server.json                    # MCP Registry manifest\n├── pyproject.toml                 # Python project configuration\n├── setup.py                       # Legacy setuptools configuration\n├── requirements.txt               # Dependencies\n├── .env.example                   # Environment configuration template\n├── .env                           # Your configuration (not in git)\n├── .gitignore                     # Git ignore patterns\n└── README.md                      # This file\n```\n\n### Running Tests\n\n```bash\n# Test server functionality\nuv run python scripts/test_server.py\n\n# Test with specific environment\nABRAFLEXI_URL=https://your-server.com uv run python scripts/test_server.py\n```\n\n## Error Handling\n\nThe server includes comprehensive error handling:\n\n- ✅ Authentication errors are clearly reported\n- 🔒 Read-only mode violations are blocked with descriptive messages\n- ✔️ Invalid parameters are validated\n- 🌐 Network and API errors are properly formatted\n- 📝 Detailed logging for troubleshooting\n\n## Security Considerations\n\n- 🔑 Store credentials securely in `.env` file (never commit to git)\n- 🔒 Enable read-only mode for monitoring-only use cases\n- 🛡️ Use HTTPS for AbraFlexi server connections\n- 🔄 Regularly rotate passwords\n- 📁 Ensure `.env` file has proper permissions (600)\n\n## Troubleshooting\n\n### Common Issues\n\n**Connection Failed:**\n- Verify `ABRAFLEXI_URL` is correct and accessible\n- Check authentication credentials\n- Ensure AbraFlexi API is enabled\n- Check firewall/network settings\n\n**Permission Denied:**\n- Verify user has sufficient AbraFlexi permissions\n- Check if read-only mode is enabled when trying to modify data\n\n**Tool Not Found:**\n- Ensure all dependencies are installed: `uv sync`\n- Verify Python version compatibility (3.10+)\n\n### Debug Mode\n\nSet environment variable for detailed logging:\n```bash\nexport DEBUG=1\nuv run python scripts/start_server.py\n```\n\n## Dependencies\n\n- [FastMCP](https://github.com/jlowin/fastmcp) - MCP server framework\n- [python-abraflexi](https://github.com/VitexSoftware/python-abraflexi) - AbraFlexi Python library\n- [python-dotenv](https://github.com/theskumar/python-dotenv) - Environment variable management\n\n## License\n\nThis project is licensed under the MIT License.\n\n## Acknowledgments\n\n- [AbraFlexi](https://www.abraflexi.eu/) for the accounting platform\n- [Model Context Protocol](https://modelcontextprotocol.io/) for the integration standard\n- [FastMCP](https://github.com/jlowin/fastmcp) for the server framework\n\n## Support\n\n- 📖 [Documentation](README.md)\n- 🐛 [Issue Tracker](https://github.com/VitexSoftware/abraflexi-mcp-server/issues)\n- 💬 [AbraFlexi API Documentation](https://podpora.flexibee.eu/cs/?q=API)\n\n## Author\n\n**Vítězslav Dvořák**\n- Email: info@vitexsoftware.cz\n- GitHub: [@VitexSoftware](https://github.com/VitexSoftware)\n\n---\n\n**Made with ❤️ for the AbraFlexi and MCP communities**\n\n<!-- mcp-name: io.github.Vitexus/abraflexi -->\n",
  "bytes": 18438,
  "sha": "132def8e3e7c72f51628bf56ab26a827d1d7f5bb19020ff2a14eafc86fc43760",
  "repo_slug": "vitexsoftware/abraflexi-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_vitexus_abraflexi_42bf114b/readme"
}