AbraFlexi

AbraFlexi MCP サーバー

FastMCP と python-abraflexi を使用して AbraFlexi と連携する、包括的な Model Context Protocol（MCP）サーバーです。このサーバーは、MCP 対応ツールを通じて AbraFlexi REST API の機能を完全に利用できます。

機能

python-abraflexi が提供する REST 機能全体を網羅した、合計 69 個のツールです。 よく使われる主なエビデンス（請求書、連絡先、製品、銀行取引）専用のツールに加えて、 名前を指定すれば あらゆる AbraFlexi エビデンスで動作する汎用の evidence_* ツールもあります。

サーバープロセス 1 つにつき AbraFlexi 会社 1 社です。 稼働中のサーバーは、 ライフサイクル全体を通じて、ABRAFLEXI_URL／ABRAFLEXI_COMPANY で指定された 1 社にバインドされます（Configuration を参照）。 いずれかのツールが返すレコードはすべて、その会社に属しています。このサーバーに別の会社のデータを 要求することはできません。server_info を呼び出すと、稼働中のサーバーがバインドされている会社／URLを 確認できます。主なレコード取得ツール（invoice_issued_get、invoice_received_get、 contact_get、product_get、bank_transaction_get、evidence_get、 changes_get）も、すべてのレスポンスの _context ブロックでその情報を返します。 さらに、レコード内の取引先フィールド（たとえば請求書の nazFirmy は顧客／仕入先を示し、 発行元／受領元の会社を示すものではありません）を明確にする注記も含まれます。

ℹ️ サーバーの識別情報

• server_info - このサーバーセッションがバインドされている AbraFlexi の会社／URLを報告します

📄 請求書の管理

• invoice_issued_get - 発行済み請求書を取得します（faktura-vydana）
• invoice_issued_create - 発行済み請求書を新規作成します
• invoice_issued_update - 発行済み請求書を更新します
• invoice_issued_delete - 発行済み請求書を削除します
• invoice_received_get - 受領済み請求書を取得します（faktura-prijata）
• invoice_received_create - 受領済み請求書を新規作成します

💳 発行済み請求書の業務処理

• invoice_issued_match_payment - 請求書と支払伝票を照合します（Párování plateb）
• invoice_issued_cash_payment - 請求書を現金で支払います（Hotovostní úhrada）
• invoice_issued_deduct_advance - 前受請求書を控除します（Odpočet záloh a ZDD）
• invoice_issued_deduct_zdd - 前受税務書類 ZDD を控除します（Odpočet záloh a ZDD）
• invoice_issued_link_zdd - ZDD を入金に関連付けます（Vazby ZDD）
• invoice_issued_unlink_zdd - ZDD の関連付けを解除します（Vazby ZDD）
• invoice_issued_overdue_days - 支払期日から延滞日数を計算します（純粋関数。API 呼び出しなし）
• invoice_issued_get_email - 請求書の最適な送信先メールアドレスを特定します
• invoice_issued_get_recipients - 請求書のすべての送信先メールアドレスを特定します

🏢 会社の管理

• company_create - AbraFlexi の新しい会社（会計単位）を設立します。サーバー管理者／ライセンスの REST 権限が必要です

👥 連絡先の管理

• contact_get - 連絡先と会社を取得します（adresar）
• contact_create - 連絡先を新規作成します
• contact_update - 既存の連絡先を更新します
• contact_delete - 連絡先を削除します

☎️ 連絡先の便利な検索

• contact_get_notification_email - 通知に最適なメールアドレス（主要な連絡先、または目的に合った連絡先）
• contact_get_cell_phone - 使用する携帯電話番号
• contact_get_any_phone - 使用可能な電話番号（固定電話より携帯電話を優先）
• contact_get_bank_accounts - 連絡先に登録されている銀行口座

📦 商品管理

• product_get - 価格表（cenik）から商品を取得
• product_create - 商品を新規作成
• product_update - 既存の商品を更新
• product_delete - 商品を削除

🏦 銀行取引の管理

• bank_transaction_get - 銀行取引（banka）を取得
• bank_transaction_create - 銀行取引を新規作成

🔧 汎用的な証憑操作

• evidence_get - 任意の証憑からレコードを取得（フィルター、ページネーション、並べ替え、関連）
• evidence_create - 任意の証憑にレコードを作成
• evidence_update - 任意の証憑のレコードを更新（remove_external_ids に対応）
• evidence_delete - 任意の証憑のレコードを削除
• evidence_list - バインドされた会社で利用可能なすべての証憑を一覧表示（ライブの evidence-list.json）

🧠 Python-abraflexi ブリッジ

• abraflexi_client_methods - python-abraflexi のコアクライアント（ReadOnly、ReadWrite、Changes、Adresar、FakturaVydana）の公開メソッドを一覧表示
• abraflexi_client_call - 選択した公開クライアントメソッドを引数付きで呼び出し（書き込みメソッドでも READ_ONLY が適用されます）

🔒 ロック、アクション、バッチ操作

• evidence_lock / evidence_unlock / evidence_lock_for_ucetni - レコードをロック／ロック解除
• evidence_storno - ドキュメントレコードを取り消し（storno）
• evidence_perform_action - レコード固有の業務アクション（例：pay）を呼び出し
• evidence_mass_update - フィルターに一致するすべてのレコードを更新、または操作（Dávkové operace）
• evidence_batch_insert / evidence_batch_update - 1 回のリクエストで複数のレコードを挿入／更新

📎 添付ファイル

• evidence_attach_file - ローカルファイルを任意のレコードに添付
• evidence_list_attachments - レコードの添付ファイルを一覧表示
• evidence_get_attachment - 単一の添付ファイルのメタデータを取得
• evidence_download_attachment - 添付ファイルをローカルファイルにダウンロード
• evidence_get_attachment_thumbnail - 画像の添付ファイルのサムネイルをダウンロード
• evidence_delete_attachment - 添付ファイルを削除

🧾 レポート、QR コード、ユーザークエリ

• evidence_export_report - レコードまたは証憑一覧の PDF/XLSX レポートをエクスポート
• evidence_get_qr_code - ドキュメントの支払い用 QR コードを取得（ファイルまたは base64 データ URI）
• user_query_list - 保存済みのユーザー定義クエリ（uzivatelsky-dotaz）を一覧表示
• call_user_query - 保存済みのユーザー定義クエリ（uživatelský dotaz）を呼び出し

ℹ️ 証憑のメタデータと合計

• evidence_get_properties - 証憑でサポートされているフィールドを一覧表示
• evidence_get_reports - 証憑で利用可能な印刷用レポートを一覧表示
• evidence_get_relations_list - 証憑で利用可能なサブ証憑（関連）を一覧表示
• evidence_get_sum - 証憑の合計を取得
• evidence_get_record_changes - 単一レコードの変更履歴を取得

🏷️ ラベル（štítky）

• evidence_get_labels - レコードに割り当てられたラベルを取得
• evidence_set_label - ラベルを追加
• evidence_unset_label - 指定したラベルを削除
• evidence_unset_labels - すべてのラベルを削除

🔄 変更 API（会社全体の差分同期）

• changes_enable / changes_disable - 変更追跡を有効化／無効化
• changes_status - 変更追跡が有効かどうかを確認
• changes_get - 指定したバージョン以降に記録された変更をページ単位で取得

インストール

前提条件

• Python 3.10 以降
• API が有効な AbraFlexi サーバーへのアクセス

オプション 1：PyPI からインストール（推奨）

pip install abraflexi-mcp-server

次に、サーバーを実行します。

abraflexi-mcp

オプション 2：AppImage（Linux）

自己完結型の AppImage を最新リリースからダウンロードします。

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

Python や pip は不要です。詳細については、AppImageのセクションを参照してください。

オプション 3：ソースからインストール

1. リポジトリをクローンします：

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

2. uv でインストールします（推奨）：

   uv sync
   uv run python scripts/start_server.py
   

   または、pip を使用します：

   pip install -e .
   abraflexi-mcp
   

クラウドへのデプロイ

テスト用のデプロイ環境を利用できます。

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

このクラウドホスト型のインスタンスを使うと、ローカルにインストールせずに AbraFlexi MCP サーバーをテストして使用できます。HTTP トランスポートを使用してこのエンドポイントに接続するよう、MCP クライアントを設定してください。

注： これはテスト用のデプロイ環境です。本番環境での使用には、上記のインストール方法のいずれかを使用してセルフホストすることをおすすめします。

設定

.env ファイルを作成するか、環境変数を設定します。

cp .env.example .env
# Edit .env with your AbraFlexi server details

設定

必須の環境変数

• ABRAFLEXI_URL - AbraFlexi サーバーの URL（例：https://demo.flexibee.eu:5434）
• ABRAFLEXI_COMPANY - 会社識別子（例：demo_de）

認証（いずれかの方法を選択）

方法 1：ユーザー名／パスワード（推奨）

• ABRAFLEXI_LOGIN - AbraFlexi のユーザー名
• ABRAFLEXI_PASSWORD - AbraFlexi のパスワード

方法 2：セッション ID

• ABRAFLEXI_AUTHSESSID - AbraFlexi のセッション ID

任意の設定

• READ_ONLY - true、1、または yes に設定すると読み取り専用モードが有効になります（デフォルト：true）
• ABRAFLEXI_TIMEOUT - リクエストのタイムアウト（秒）（デフォルト：300）

トランスポートの設定

• ABRAFLEXI_MCP_TRANSPORT - トランスポートの種類：stdio（デフォルト）または streamable-http

HTTP トランスポートの設定（ABRAFLEXI_MCP_TRANSPORT=streamable-http の場合のみ使用）：

• ABRAFLEXI_MCP_HOST - サーバーのホスト（デフォルト：127.0.0.1）
• ABRAFLEXI_MCP_PORT - サーバーのポート（デフォルト：8000）
• ABRAFLEXI_MCP_STATELESS_HTTP - ステートレスモード（デフォルト：false）
• AUTH_TYPE - streamable-http トランスポートでは no-auth に設定する必要があります

使用方法

サーバーの実行

起動スクリプトを使用（推奨）：

uv run python scripts/start_server.py

直接実行：

uv run python -m abraflexi_mcp_server.server

CLI のヘルプ：

abraflexi-mcp --help

トランスポートのオプション

サーバーは 2 種類のトランスポート方式に対応しています。

STDIO トランスポート（デフォルト）

Claude Desktop などの MCP クライアント向けの標準入出力トランスポート：

# Set in .env or environment
ABRAFLEXI_MCP_TRANSPORT=stdio

HTTP トランスポート

Web 連携向けの HTTP ベースのトランスポート：

# 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

テスト

テストスイートを実行：

uv run python scripts/test_server.py

読み取り専用モード

READ_ONLY=true（デフォルト）の場合、サーバーが公開するのは GET 操作（データの取得）のみで、作成、更新、削除の操作はすべてブロックされます。次の用途に便利です。

• 📊 モニタリングダッシュボード
• 🔍 読み取り専用の連携
• 🔒 セキュリティを重視する環境
• 🛡️ 誤った変更の防止

書き込み操作を有効にするには、.env ファイルで READ_ONLY=false に設定します。

ツール呼び出しの例

発行済みの請求書をすべて取得：

invoice_issued_get(limit=10)

コードを指定して請求書を取得：

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

2026 年 8 月に発行された請求書の件数を取得（レコード全体はダウンロードしない）：

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

新しい連絡先を作成：

contact_create(
    kod="CUSTOMER01",
    nazev="Example Company s.r.o.",
    email="[email protected]",
    tel="+420123456789"
)

商品を取得：

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

汎用証憑クエリ（ページネーション／ソート対応）：

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

ローカルファイルを任意のレコードに添付：

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

請求書をロックしてから 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"
)

仕入先の商品価格表の全項目を一括更新：

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

Changes API を使用した差分同期：

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

MCP 連携

このサーバーは、Claude Desktop などの MCP 互換クライアントで動作するように設計されています。連携方法の詳細については、MCP_SETUP.mdを参照してください。

OCI コンテナ

このサーバーは OCI コンテナ（Docker／Podman）として実行できます。ホストへの Python のインストールは不要です。

イメージのビルド

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

コンテナの実行

イメージはデフォルトで、ポート 8000 で streamable-http トランスポートを使用します。

個別の環境変数を使用：

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

env ファイルを使用：

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

コンテナー環境のデフォルト値

変数	デフォルト値
ABRAFLEXI_MCP_TRANSPORT	streamable-http
ABRAFLEXI_MCP_HOST	0.0.0.0
ABRAFLEXI_MCP_PORT	8000
READ_ONLY	true

その他の設定変数は、環境変数として渡すことができます。

AppImage

ホストに Python、pip、その他の依存関係が不要な、自己完結型の単一ファイルの Linux 実行可能ファイルです。

AppImage のビルド

bash appimage/build-appimage.sh

このスクリプトは、ポータブル版の CPython と appimagetool を自動でダウンロードします。生成されたファイルは build/appimage/ に配置されます。

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

AppImage の実行

AppImage は、現在の作業ディレクトリに .env ファイルがあれば、自動的に読み込みます。

.env ファイルを使用する場合（推奨）：

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

環境変数を直接指定する場合：

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

開発

プロジェクト構成

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

テストの実行

# Tool registration + basic connectivity
uv run python scripts/test_server.py

# Live capability scenario (all read tools + READ_ONLY write guards)
# Official public demo (login winstrom / winstrom):
python tests/live_capability_scenario.py \
  --url https://demo.flexibee.eu:5434 \
  --company demo \
  --login winstrom --password winstrom \
  --json-out /tmp/abra-demo-live.json

# Private/dev company example:
python tests/live_capability_scenario.py \
  --url https://flexibee-dev.spoje.net:5434 \
  --company testa_invest_s_r_o_ \
  --login "$ABRAFLEXI_LOGIN" --password "$ABRAFLEXI_PASSWORD" \
  --json-out /tmp/abra-live.json

スキップされていないチェックが失敗すると、終了コードはゼロ以外になります。

エラー処理

サーバーには、包括的なエラー処理が含まれています。

• ✅ 認証エラーが明確に報告されます
• 🔒 読み取り専用モードへの違反は、内容を明示したメッセージとともにブロックされます
• ✔️ 無効なパラメーターが検証されます
• 🌐 ネットワークエラーと API エラーが適切な形式で出力されます
• 📝 トラブルシューティング用の詳細なログが記録されます

セキュリティに関する考慮事項

• 🔑 認証情報は .env ファイルに安全に保存してください（git にコミットしないでください）
• 🔒 監視のみを行う用途では、読み取り専用モードを有効にしてください
• 🛡️ AbraFlexi サーバーとの接続には HTTPS を使用してください
• 🔄 パスワードは定期的に変更してください
• 📁 .env ファイルに適切な権限（600）が設定されていることを確認してください

トラブルシューティング

よくある問題

接続に失敗する場合：

• ABRAFLEXI_URL が正しく、アクセス可能であることを確認してください
• 認証情報を確認してください
• AbraFlexi API が有効になっていることを確認してください
• ファイアウォールとネットワークの設定を確認してください

アクセスが拒否される場合：

• ユーザーに十分な AbraFlexi 権限があることを確認してください
• データを変更しようとしているときに、読み取り専用モードが有効になっていないか確認してください

ツールが見つからない場合：

• すべての依存関係がインストールされていることを確認してください：uv sync
• Python のバージョンが互換性要件（3.10 以降）を満たしていることを確認してください

デバッグモード

詳細なログを記録するには、環境変数を設定します。

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

依存関係

• FastMCP - MCP サーバーのフレームワーク
• python-abraflexi - AbraFlexi Python ライブラリ
• python-dotenv - 環境変数の管理

ライセンス

このプロジェクトは MIT ライセンスのもとでライセンスされています。

謝辞

• 会計プラットフォームを提供する AbraFlexi
• 統合標準を提供する Model Context Protocol
• サーバーのフレームワークを提供する FastMCP

サポート

• 📖 ドキュメント
• 🐛 課題トラッカー
• 💬 AbraFlexi API ドキュメント

作者

Vítězslav Dvořák

• メール：[email protected]
• GitHub：@VitexSoftware

---

AbraFlexi と MCP のコミュニティのために ❤️ を込めて作られました