UOL Účetnictví (unofficial)

uol-mcp

UOL Účetnictví 向けの Model Context Protocol サーバーです。Claude、Cursor、その他の MCP クライアントから、発行・受領した請求書、売掛金、アップロード済み書類、連絡先について質問できます。

非公式です。 UOL a.s. とは提携も承認関係もありません。独自の API トークンを使って公開 UOL REST API にアクセスします。

チェコ語

ステータス： v0.6 — デフォルトでは読み取り専用で、書き込みはオプトインです。変更点：CHANGELOG.md。

できること

ツール	回答できる内容
get_business_snapshot	1 回の呼び出しで会社の状況を確認できます。今月と前月の比較、VAT、売掛金、処理が必要な書類、銀行
get_financial_overview	総勘定元帳から月ごとの収益、費用、利益、残高の大きい勘定
get_vat_overview	申告期間ごとの VAT：納付額または控除超過額、納期限、確定値または推定値
get_bank_balances	口座および通貨ごとの銀行残高（UOL は月次スナップショットを保持します）
get_company	会社名、IČO、DIČ、住所、VAT 申告期間。接続確認にも使えます
search_sales_invoices、get_sales_invoice	発行済み請求書。明細、VAT、支払い状況を含みます
search_purchase_invoices、get_purchase_invoice	受領した請求書
list_receivables	誰がいくら未払いか、延滞期間、通貨ごとの合計
export_sales_invoice	発行済み請求書の PDF または ISDOC をディスクに保存します（ISDOC は XML としても返されます）
search_contacts、get_contact	顧客と仕入先を名前、IČO、DIČ で検索し、住所と銀行口座を確認できます
list_uploaded_documents、get_uploaded_document、download_uploaded_document	会計士向けにアップロードされた書類、その状態とファイル
list_codebook	通貨、部門、契約、価格表、自社の銀行口座など
api_get	その他の /v1/… エンドポイントに対する読み取り専用 GET

質問の例：「今年の業績はどうですか？」、「今四半期の VAT 納付額はいくらですか？」、 「30 日以上延滞している未払いは誰のものですか？」、「請求書 2026000123 は支払い済みですか？」、 「最も支出が多い項目は何ですか？」、「直近の発行済み請求書の PDF をダウンロードして。」

追加の読み取りツールは、オプトインのツールセット（UOL_TOOLSETS）で利用できます。ledger（総勘定元帳の仕訳、社内書類）、banking（銀行取引、小口現金書類）、warehouse（商品、在庫水準、注文）があります。

すぐに使えるプロンプト（多くのクライアントでスラッシュコマンドとして使えます）：monthly_review、vat_check、 overdue_followup（リマインダーを作成しますが、送信はしません）、process_inbox、および 書き込みアクセスを有効にした場合の issue_invoice（説明から売上請求書を作成し、ドライランを表示して、確認後に下書きを作成します）。uol://guide リソースでは、モデルに向けてこの分野の説明を提供します。

uol-ucetnictvi スキルを使うと、さらに多くのことができます。Claude は、以前にその顧客へ発行した請求書から学んだ方法（DUZP のルール、支払期限、商品、明細テキスト、銀行口座）に従って請求書を発行し、会計士と同じ方法で収益、利益、VAT、売掛金を読み取ります（未記帳月、推定値、期限など）。Claude Desktop または claude.ai にインストールするには、skills/uol-ucetnictvi フォルダーを zip 化し、Settings → Capabilities → Skills からアップロードします。Claude Code の場合は、フォルダーを ~/.claude/skills/ にコピーします。

このサーバーは API の特有の挙動に対応しています。請求書のステータス valid は 下書き を意味します。支払い状況は発行済み請求書にのみ存在します。クレジットノートの金額は正の値で返されます。収益と費用は元帳から読み取る必要があります（年末決算仕訳を除く）。仕入請求書では発行日のフィルターが無視されます。ファイルのダウンロード形式は 3 種類あり、レート制限（10 秒あたり 30 リクエスト）はクライアント側で遵守されます。docs/DESIGN.md を参照してください。

API トークンの取得

1. UOL テナントの API トークンページ（パス /api_tokens、例： https://firma.ucetnictvi.uol.cz/api_tokens）を開き、トークンを作成します。
2. UOL ユーザーには REST API 権限が必要です。アシスタントに付与したい権限のみを持つ専用ユーザーを用意することをおすすめします。

テナント名は、UOL アドレスの最初の部分です。https://firma.ucetnictvi.uol.cz → firma。

まず試してみたい場合は、UOL_TENANT=demo を指定すると、トークンなしで UOL の公開 DEMO 会社を利用できます。

設定

変数	意味
UOL_TENANT	demo、テナント名（firma）、ホストのプレフィックス（firma.sandbox）、または完全な https://….uol.cz URL
UOL_EMAIL	UOL へのログインに使用するメールアドレス
UOL_TOKEN	API トークン
UOL_DOWNLOAD_DIR	エクスポートおよびダウンロードしたファイルの保存先（デフォルトは ~/Downloads/uol-mcp）
UOL_TOOLSETS	カンマ区切りで指定：core、insights（この2つがデフォルト）、ledger、banking、warehouse、または all
UOL_ACCESS	read（デフォルト）、write、または full — 書き込みを参照
UOL_PROMPT_LANGUAGE	プロンプト（スラッシュコマンド）と、それに応じて求める回答の言語：cs（デフォルト）または en
UOL_ACCOUNTS、UOL_DEFAULT_ACCOUNT	1つのサーバーで複数の会社を利用 — 複数の会社を参照。UOL_ACCOUNT_<NAME>_ACCESS で各アカウントのアクセスレベルを設定します
UOL_PROFILES_FILE	同じ設定を JSON ファイルから指定します
UOL_UPLOAD_DIRS	upload_document が読み取れるフォルダー（デフォルトは ~/Downloads、~/Desktop、~/Documents。区切り文字は :、Windows では ;）。HTTP サーバーにはデフォルト値がありません。この変数を設定しない場合、content_base64 のみ受け付けます
UOL_AUDIT_LOG	すべての書き込みを JSON の1行形式で記録するファイル
UOL_TIMEOUT_MS	1回の UOL リクエストのタイムアウト（デフォルトは 30000）
UOL_DEBUG	1 を指定すると、認証情報を除くリクエストを stderr に記録します

Claude Desktop

「設定」→「開発者」→「設定を編集」の順に開き、次を追加します。

{
  "mcpServers": {
    "uol": {
      "command": "npx",
      "args": ["-y", "uol-mcp"],
      "env": {
        "UOL_TENANT": "firma",
        "UOL_EMAIL": "[email protected]",
        "UOL_TOKEN": "your-token"
      }
    }
  }
}

Claude Code

claude mcp add uol -e UOL_TENANT=firma -e [email protected] -e UOL_TOKEN=your-token -- npx -y uol-mcp

Cursor / VS Code

Cursor（.cursor/mcp.json）では、Claude Desktop と同じ mcpServers ブロックを使用します。VS Code （.vscode/mcp.json）では次のように設定します。

{
  "servers": {
    "uol": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "uol-mcp"],
      "env": { "UOL_TENANT": "firma", "UOL_EMAIL": "[email protected]", "UOL_TOKEN": "your-token" }
    }
  }
}

Docker

docker run -i --rm -e UOL_TENANT=firma -e [email protected] -e UOL_TOKEN=your-token -v "$HOME/Downloads/uol-mcp:/data" ghcr.io/jakubbegera/uol-mcp

エクスポートおよびダウンロードしたファイルは、コンテナー内の /data に書き込まれます。-v マウントによってファイルが保持されます。 MCP クライアントの設定では、コマンドに docker を指定し、残りを args に指定します。

Claude Desktop 拡張機能

各リリースには uol-mcp.mcpb が含まれています。これを開いてインストールし、フォームでテナント、メールアドレス、トークンを入力します。トークンはシークレットとして保存されます。bash scripts/build-mcpb.sh を実行すると、ソースからバンドルをビルドできます。

HTTP サーバー（セルフホスト）

MCP_TRANSPORT=http MCP_AUTH_TOKEN=$(openssl rand -hex 32) UOL_TENANT=firma [email protected] UOL_TOKEN=your-token npx -y uol-mcp

エンドポイントは http://127.0.0.1:3000/mcp です（変更する場合は HOST、PORT を設定してください。プローブには /health を使用します）。 2 つのモードがあります。

• 単一テナント：UOL の認証情報をサーバーの環境変数に設定します。クライアントは Authorization: Bearer <MCP_AUTH_TOKEN> を送信する必要があります。トークンがない場合、サーバーは起動を拒否します。
• パススルー：環境変数に UOL の認証情報を設定しません。各クライアントはリクエストごとに独自の X-UOL-Tenant、 X-UOL-Email、X-UOL-Token ヘッダーを送信します。サーバーは何も保存しません。 localhost では MCP_AUTH_TOKEN は任意です。

HTTP 経由では、エクスポートした請求書とダウンロードしたドキュメントはサーバーに保存されず、ツールの結果に含まれて返されます。また、upload_document はファイルを content_base64 として受け取り、UOL_UPLOAD_DIRS が設定されていない限り、サーバー上のパスを読み取りません。Docker では、すべてのインターフェースにバインドしてポートを公開してください：docker run -p 3000:3000 -e MCP_TRANSPORT=http -e HOST=0.0.0.0 -e MCP_AUTH_TOKEN=… -e MCP_ALLOWED_HOSTS=mcp.example.com …。

変数	意味
MCP_TRANSPORT	http を指定すると HTTP サーバーを起動します（--http と同じです）
HOST、PORT	バインドアドレス。デフォルトは 127.0.0.1:3000 です
MCP_AUTH_TOKEN	クライアントが送信する必要のあるベアラートークン。32 文字以上が必要です。単一テナントモード、および HOST がループバックアドレスでない場合は必須です
MCP_ALLOWED_HOSTS	許可する Host 名（カンマ区切り）。HOST がループバックアドレスでない場合は必須です
MCP_ALLOWED_ORIGINS	エンドポイントへの呼び出しを許可するブラウザーのオリジン（デフォルトでは許可なし）

サーバーは平文 HTTP を使用します。localhost の外部で使う場合は、TLS を終端するリバースプロキシの背後に配置してください。MCP_AUTH_TOKEN と MCP_ALLOWED_HOSTS が設定されていない場合、サーバーはループバック以外のアドレスでの起動を拒否します。

セットアップを確認する

UOL_TENANT=firma [email protected] UOL_TOKEN=your-token npx -y uol-mcp doctor

書き込み（オプトイン）

UOL_ACCESS=write を設定すると、次のツールが表示されます。

ツール	機能
upload_document	会計担当者用の UOL ドキュメント受信箱に PDF をアップロードします（UOL_UPLOAD_DIRS 内からのみ）
create_sales_invoice	既存の連絡先に対する発行済み請求書を作成します。issue: true を指定しない場合は下書きです。number を指定すると印刷される請求書番号が設定されます。指定しない場合、UOL は番号系列の次の番号を使用します
update_sales_invoice	下書き請求書を変更または発行します。請求書番号も変更できます（UOL では発行済み請求書を編集できません）
create_purchase_invoice	既存の仕入先から受け取った請求書を登録します
create_contact、update_contact	顧客または仕入先を追加または変更します（重複する IČO は拒否されます）
create_payment_demand	1 社の顧客の未払い請求書に対する支払い督促（upomínka）を作成します。送信はしません
mark_document_processed、pair_uploaded_document、tag_uploaded_document、untag_uploaded_document	会計担当者用の受信箱を操作します：状態、登録済みレコードへのリンク、タグ

UOL_ACCESS=full を設定すると、delete_sales_invoice（下書きのみ）、repair_sales_invoice（発行済み請求書を取り消すか、下書きに戻す）、api_request（任意のエンドポイントへの生の書き込み）が追加されます。

請求書の明細には UOL の商品が必要です（kind: products を指定して list_codebook を実行すると一覧を確認できます）。すべての書き込みで dry_run を使用でき、送信内容を正確に確認できます。作成処理は安全に再試行できます（冪等性キー）。また、クライアントが実行前に確認するよう、ツールにマークが付けられています。すべての書き込みの記録を残すには、UOL_AUDIT_LOG を設定してください。

複数の会社

UOL に複数のクライアントを持つ会計士は、1 つのサーバーからすべてのクライアントに対応できます。アカウントを UOL_ACCOUNTS に列挙し、それぞれに専用の変数を設定します（名前は大文字にし、- は _ に置き換えます）。

"env": {
  "UOL_ACCOUNTS": "firma,novak",
  "UOL_ACCOUNT_FIRMA_TENANT": "firma",
  "UOL_ACCOUNT_FIRMA_EMAIL": "[email protected]",
  "UOL_ACCOUNT_FIRMA_TOKEN": "op://Private/UOL firma/credential",
  "UOL_ACCOUNT_NOVAK_TENANT": "novak",
  "UOL_ACCOUNT_NOVAK_EMAIL": "[email protected]",
  "UOL_ACCOUNT_NOVAK_TOKEN": "op://Private/UOL novak/credential",
  "UOL_ACCOUNT_NOVAK_LABEL": "Novák s.r.o."
}

最初のアカウントがデフォルトになります（または UOL_DEFAULT_ACCOUNT を設定してください）。1Password CLI を使う場合は、サーバーを op run -- node …/dist/index.js で起動すると、起動時に op:// の参照がトークンに置き換えられます。設定にシークレットが残ることはありません。uol-mcp doctor はすべてのアカウントを確認します。

または、UOL_PROFILES_FILE に JSON ファイルを指定できます。

{
  "default": "firma",
  "accounts": {
    "firma": { "tenant": "firma", "email": "[email protected]", "token_env": "UOL_TOKEN_FIRMA" },
    "novak": { "tenant": "novak", "email": "[email protected]", "token_env": "UOL_TOKEN_NOVAK", "label": "Novák s.r.o." }
  }
}

token_env はトークンを格納する環境変数を指定するため、ファイルにシークレットを含める必要はありません（インラインの token も使用できますが、その場合はファイルを chmod 600 にしてください）。サーバーは list_accounts を提供し、すべてのツールで account 引数を指定できます。「Kdo dluží firmě Novák?」 は適切なテナントに送られます。各アカウントにはそれぞれのレート制限が適用されます。

アカウントごとにアクセスレベルを設定できます。UOL_ACCESS=write と UOL_ACCOUNT_NOVAK_ACCESS=read（またはプロファイルファイルで "access": "read"）を設定すると、Novák への書き込みは拒否されますが、他のアカウントへの書き込みは引き続き可能です。list_accounts には各アカウントのアクセスレベルが表示されます。

プライバシーと安全性

• UOL_ACCESS=write を設定しない限り、読み取り専用です。請求書、メモ、書類内のテキストはデータとして扱われます。書き込みを承認する前に、アシスタントが書き込もうとしている内容を確認してください。
• ツールが返す内容は、クライアントが使用する AI モデルに送られます。会計データには、連絡先や従業員の個人データが含まれます。利用規約に納得できるプランを使用してください。
• 認証情報は https://*.uol.cz に対してのみ使用され、ログやツールの出力に書き込まれることはありません。
• ダウンロードしたファイルは UOL_DOWNLOAD_DIR の下にのみ保存され、所有者だけが読み取り可能です。既存のファイルが置き換えられることはありません（同名のファイルがある場合は (1) が追加されます）。50 MB を超えるダウンロードは拒否されます。
• モデルには、UOL から届くテキスト（請求書、メモ、書類）はデータであり、指示ではないと伝えられます。

ソースからのインストール

Node.js 22 以降が必要です。

git clone https://github.com/jakubbegera/uol-mcp.git
cd uol-mcp
npm install
npm run build

その後、npx -y uol-mcp の代わりに node /path/to/uol-mcp/dist/index.js をクライアントに指定してください。

開発

npm test                 # unit + MCP-level tests against recorded DEMO responses
npm run typecheck
npm run smoke            # calls every tool against the live DEMO tenant
npm run record-fixtures  # refreshes test/fixtures/demo from the DEMO tenant
bash scripts/build-mcpb.sh  # builds build/uol-mcp.mcpb
docker build -t uol-mcp .

CI では、型チェック、テスト、npm audit、Docker イメージの Trivy スキャン、CodeQL、およびプルリクエストでの依存関係レビューが実行されます。Dependabot により、依存関係、アクション、ベースイメージが最新の状態に保たれます。

リリースは v* タグをプッシュして作成します。メンテナーが release 環境を承認すると、.github/workflows/release.yml によって npm、GHCR、GitHub リリース（MCPB バンドル）、MCP Registry に公開されます。

設計上の注意点、API に関する情報、ロードマップについては、docs/DESIGN.md をご覧ください。

貢献

貢献を歓迎します。CONTRIBUTING.md をご覧ください。セキュリティ上の問題は、SECURITY.md の説明に従って非公開で報告してください。

ライセンス

MIT