Clover POS

clover-mcp

Clover POS REST API 用の MCP サーバーです。AI アシスタント（Claude、Cursor など）から、Clover マーチャントの売上、在庫、注文、顧客データへの読み取りと安全な書き込みを可能にします。

ステータス： v0.7.0 をリリース済み。作業ツリー（未リリース）には、56 個のツール、6 個のプロンプト、両方の認証モード、399 件のテストが含まれています。ローカル（stdio、単一マーチャント）または OAuth を使用した HTTP 経由のリモート環境で実行できます。シングルテナントとマルチテナントの両方に対応しています（docs/DEPLOY.md を参照）。エンドポイントのコントラクトは docs/endpoints.md でサンドボックス検証済みです。

⚠️ 独立したプロジェクトです。Clover Network, LLC または Fiserv, Inc. との提携、承認、後援関係はありません。 「Clover」はそれぞれの所有者の商標であり、相互運用性を説明する目的に限って使用しています。保証のない 現状有姿 で提供されます。法的事項と免責事項を参照してください。

できること

• 売上の概要、決済および返金レポート
• 在庫の照会と在庫僅少アラート
• 注文履歴と未完了注文の確認
• 顧客の検索と作成
• 従業員、シフト、役割、カテゴリー、モディファイア、税、支払い方法、デバイスの照会、および売れ筋商品
• 価格設定の構成の照会：割引カタログ、チップ提案のプリセット、デフォルトのサービス料
• 安全な書き込み：商品の価格の更新、在庫数の設定、顧客／商品／カテゴリー／注文の作成、注文明細の追加、顧客の更新、商品の名称変更、注文への割引適用、モディファイアグループ／モディファイア／タグの作成
• AI ツール（クライアントのモデルを使って推論します。サーバーは LLM キーを保持しません）：売上の報告、発注提案、異常検知、カテゴリー提案、顧客向けメッセージの下書き
• 定義済みのプロンプトワークフロー：日次報告、週次売上レポート、在庫健全性チェック、終業時締め処理、顧客検索、月次税務サマリー

設計上、できないこと： 返金処理、決済の確定、請求の無効化、レコードの削除。これらは Clover ダッシュボードで行います。

ツール

ツール	種類	備考
get_merchant_info / get_merchant_properties	読み取り	プロフィール + POS 設定（銀行関連のフィールドは返されません）
get_sales_summary	読み取り	集計期間（売上サマリーの仕様を参照）
get_sales_by_employee / get_tips_by_employee / get_sales_by_hour	読み取り	従業員別の売上、チップの分配、および加盟店の現地時間に基づく時間帯別レポート（PAYMENTS_R；従業員名は可能な範囲で取得されます）
list_payments / list_refunds / list_credits / list_tenders	読み取り	支払い、返金、クレジット、決済方法
list_orders / get_order / list_open_orders / list_order_types	読み取り	注文履歴 + 詳細
list_items / get_item / list_low_stock_items	読み取り	在庫 + 商品；get_item(include=[...]) で modifier_groups/tax_rates/categories/tags の関連詳細を取得できます
list_categories / list_modifiers / list_taxes / list_item_groups / list_attributes / list_tags / list_discounts	読み取り	カタログ構造
list_tip_suggestions / get_default_service_charge	読み取り	チップのプリセット + サービス料の設定
list_devices / list_opening_hours / list_cash_events	読み取り	端末、営業時間、キャッシュドロワーの記録
get_top_items	読み取り	期間内の販売数量に基づく売れ筋商品
list_employees / get_employee / list_shifts / list_active_shifts / list_roles	読み取り	PIN は返されません（EMPLOYEES_R）
search_customers / get_customer	読み取り	カード情報は返されません
whoami	読み取り	マルチテナントの ID 診断（シークレット情報なし）
summarize_sales / inventory_reorder_suggestions / detect_sales_anomalies / suggest_item_categories / draft_customer_message	AI	クライアントのモデルで推論する読み取り専用の提案
create_customer / update_customer	書き込み	重複チェック + dry_run；更新はエリシテーションで確認
create_item / create_category / create_order / add_line_item	書き込み	保護機能付き：書き込み前に dry_run + 確認
set_item_price_cents / set_item_stock_quantity / update_item_name	書き込み	楽観ロックによる事前チェック、範囲制限、dry_run
apply_order_discount	書き込み	percentage / amount_cents / catalogue_discount_id のいずれか1つのみ；正の amount_cents を Clover が要求する負のワイヤー値に変換；カタログ経由ではクライアント側で名前と値を解決；dry_run のプレビューにはクライアント側で計算した明細小計が含まれます
create_modifier_group / create_modifier / create_tag	書き込み	重複防止（グループ/タグ）または親の事前チェック（モディファイア）；保護機能付き：書き込み前に dry_run + 確認

すべてのツールには MCP の動作アノテーション（readOnlyHint / destructiveHint / idempotentHint）が付与されているため、クライアントは読み取りを並列実行し、書き込み前に確認を求めることができます。

インストール

PyPI で公開されています。クローンは不要です：

uvx clover-mcp          # run directly (recommended)
# or
pip install clover-mcp  # then launch with: clover-mcp

ソースから（開発用）：

git clone https://github.com/SBolivarLoL/clover-mcp-server
cd clover-mcp-server
uv pip install -e .

設定

.env.example を .env にコピーし、値を入力します：

cp .env.example .env

必須：

変数	説明
CLOVER_MERCHANT_ID	Clover の加盟店 ID
CLOVER_ACCESS_TOKEN	Clover API アクセストークン

任意：

変数	デフォルト	説明
CLOVER_REGION	na	na、eu、または la
CLOVER_SANDBOX	false	Clover のサンドボックスを使用する場合は true
CLOVER_AUTH_MODE	token	token または oauth_refresh
CLOVER_READ_ONLY	false	Clover にリクエストを送る前に、すべての書き込みを拒否します
CLOVER_WRITE_LIMIT_COUNT	10	安全期間内の最大書き込み回数；0 で無効化され、負の値は拒否されます
CLOVER_WRITE_LIMIT_WINDOW_S	300	書き込み安全期間（秒）。正の値を指定します

認証モード

• token — 静的なアクセストークンを貼り付けます。サンドボックスおよび単一マーチャントの本番環境で使用できます。トークンの有効期限が切れた場合は、Clover Developer Dashboard で再生成してください。
• oauth_refresh — 有効期限が切れると、サーバーが自動的にトークンを更新し、新しいトークンペアを CLOVER_TOKEN_STORE（デフォルト：~/.config/clover-mcp/tokens.json、モード 0600）に保存します。Clover のリフレッシュトークンは一度しか使えないため、更新のたびに新しいペアを書き戻します。トークンを取得するには scripts/get_sandbox_token.py を実行してください。トークンはストアに直接書き込まれるため、.env では CLOVER_AUTH_MODE、CLOVER_OAUTH_CLIENT_ID、CLOVER_OAUTH_CLIENT_SECRET、CLOVER_MERCHANT_ID のみを設定します（トークン値は不要です）。代替手段として、.env に CLOVER_ACCESS_TOKEN／CLOVER_REFRESH_TOKEN を貼り付ける方法も引き続き使用できます。

最小権限のトークンを使用してください。 実際に使用するツールに必要な権限スコープのみを付与してください（以下の表を参照）。読み取り専用のデプロイでは、*_W スコープは一切不要です。本番環境のトークンをサンドボックスで使用したり、その逆を行ったりしないでください。

Claude Desktop のセットアップ

~/Library/Application Support/Claude/claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "clover": {
      "command": "uvx",
      "args": ["clover-mcp"],
      "env": {
        "CLOVER_MERCHANT_ID": "your_merchant_id",
        "CLOVER_ACCESS_TOKEN": "your_token",
        "CLOVER_REGION": "na"
      }
    }
  }
}

Cursor のセットアップ

プロジェクト内の .cursor/mcp.json（またはグローバル設定の ~/.cursor/mcp.json）に追加します。

{
  "mcpServers": {
    "clover": {
      "command": "uvx",
      "args": ["clover-mcp"],
      "env": {
        "CLOVER_MERCHANT_ID": "your_merchant_id",
        "CLOVER_ACCESS_TOKEN": "your_token"
      }
    }
  }
}

必要な Clover 権限

トークンには、次の Clover 権限スコープが必要です。

権限	使用するツール
MERCHANT_R	get_merchant_info
ORDERS_R	list_orders、get_order、list_open_orders
PAYMENTS_R	list_payments、list_refunds、list_credits、get_sales_summary、get_sales_by_employee、get_tips_by_employee、get_sales_by_hour
ORDERS_R	…get_top_items でも使用
INVENTORY_R	list_items、get_item、list_low_stock_items、list_categories、list_modifiers、list_taxes、list_discounts、list_item_groups、list_attributes、list_tags
INVENTORY_W	set_item_price_cents、set_item_stock_quantity、create_item、create_category、update_item_name、create_modifier_group、create_modifier、create_tag
ORDERS_W	create_order、add_line_item、apply_order_discount
CUSTOMERS_R	search_customers、get_customer
CUSTOMERS_W	create_customer、update_customer
EMPLOYEES_R	list_employees、get_employee、list_shifts、list_active_shifts、list_roles（任意）
MERCHANT_R	…list_devices、list_tenders、list_order_types、list_opening_hours、list_cash_events、list_tip_suggestions、get_default_service_charge でも使用

読み取りスコープ（*_R）は起動時に確認され、不足しているものがあればサーバーが警告します（サーバーは終了せず、ホスト型サーバーも起動できるようになりました）。該当するツールを呼び出すと 403 が返されます。EMPLOYEES_R は任意です。書き込みスコープ（*_W）は確認されません（確認によってデータが変更されるためです）。書き込みスコープが不足している場合、そのツールを初めて呼び出したときに 403 が返されます。Clover アプリの権限を変更するには、マーチャントがアプリを再インストールする必要があります。

リモート／ホスト型（v2）

デフォルトでは、単一マーチャント向けに stdio 経由でローカル実行します。リモートで実行するには、次の方法があります。

• FastMCP Cloud / Horizon（最も簡単）： エントリーポイントに server.py:mcp を指定してデプロイし、 プラットフォーム組み込みの認証を有効にして、単一マーチャント用の Clover 環境変数を設定します。 OAuth、HTTPS、トランスポートはプラットフォームが処理します。IdP の設定は不要です。また、この方法では CLOVER_TRANSPORT／CLOVER_AUTH_* を設定しないでください（この設定では IdP が必要となり、失敗します）。
• セルフホスト： server.py:create_server を使用します。これにより clover-mcp は OAuth 2.1 のリソースサーバーとして動作し（IdP の JWT を検証し、RFC 9728 に準拠した Protected Resource Metadata を公開し、トークンのクレームに基づいてルーティングします）、IdP がない場合は起動を拒否するため、 認証なしで実行されることはありません。

両方の詳細なセットアップ手順は docs/DEPLOY.md を参照してください。SSO／SAML、SCIM、 監査、マルチテナント認可の連携については、docs/enterprise-identity.md を参照してください。

売上サマリーの意味

get_sales_summary は会計処理を明示するため、LLM が説明できます。

• 総売上 = result=SUCCESS の支払い金額の合計です。FAIL／AUTH／未キャプチャの PRE_AUTH は除外されます。
• 返金は専用の /refunds エンドポイントから取得します（Clover の返金は正の金額を持つ別個のオブジェクトであり、負の支払いではありません）。取消は取り消された支払いから集計します。いずれも別々に報告され（refund_count／refund_amount、void_count）、payment_count に差し引きで反映されることはありません。net_sales = gross_sales - refund_amount です。
• チップと税金はそれぞれ独立した明細として集計されます。
• サービス料は個別に報告されません。Clover では注文上の割合としてのみ公開され（算出済み金額はありません）、顧客が実際に支払った金額はすでに支払い合計を通じて gross_sales に含まれているためです。
• オフライン決済も含まれます。該当する期間にオフライン決済がある場合は、note で示されます。
• 通貨は加盟店レコードから取得し、デフォルト値は使用しません。
• 90 日を超える期間は分割され、透過的に連結されます。

開発

uv pip install -e ".[dev]"
pytest
ruff check src/ tests/ scripts/
ruff format --check src/ tests/ scripts/
mypy src/clover_mcp/

サンドボックスに対する正確性評価とレイテンシ／負荷ベンチマーク： uv run python scripts/benchmark.py — 方法、結果、失敗分析については docs/eval.md を参照してください。

アーキテクチャ（図とモジュールマップ）：docs/ARCHITECTURE.md。 5 分間のデモを実行するには、uv run python scripts/demo.py を実行します（または docs/DEMO.md の手順書を参照してください）。

可観測性

可観測性に関する出力はすべて stderr に出力されます（stdout は MCP の stdio プロトコルに使用されます）。

• 監査ログ（デフォルトで有効） — 書き込みのたびに、構造化された JSON の 1 行が出力されます： {"ts":"2026-07-02T…Z","audit":"write","method":"PUT","path":"/items/…","status":200,"merchant":"…"}。 UTC の ts は発生時刻を記録します。マルチテナントモードでは、tenant フィールドに対象を記録します。 リクエスト本文やシークレットは含まれません。無効にするには CLOVER_AUDIT_LOG=false を設定します。

• レイテンシログ — CLOVER_LATENCY_LOG=true を設定すると、Clover への HTTP 呼び出しごとに latency_ms の行が出力されます。

• 分散トレース（任意） — OpenTelemetry の追加機能をインストールしてコレクターを指定すると、Clover への各呼び出しがスパンになります。追加機能がない場合、トレースはコストのかからない no-op です（依存関係は追加されません）。

  uv pip install -e ".[otel]"
  export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
  export OTEL_SERVICE_NAME=clover-mcp
  

セキュリティ

脆弱性の開示ポリシーについては、SECURITY.md を参照してください。

法的事項および免責事項

これは法的助言ではありません。以下の注記では、プロジェクトの意図と 運用者の責任について説明します。

• 提携関係はありません。 これは独立したコミュニティプロジェクトです。Clover Network, LLC または Fiserv, Inc. とは一切 提携、承認、後援の関係にありません。「Clover」および関連する標章は、それぞれの所有者の商標であり、 このソフトウェアが Clover REST API と相互運用することを示すために、名称を示す目的でのみ使用しています。 Clover のロゴやブランドは使用していません。
• 保証なし／責任なし。 本ソフトウェアは、いかなる種類の保証もなく、MIT License に基づき **「現状のまま」**提供されます。著者は、誤ったデータ、意図しない書き込み、ダウンタイム、著者の管理が及ばない API の変更など、 本ソフトウェアの使用に起因するいかなる請求、損害、損失についても責任を負いません。
• 運用するのは利用者であり、責任も利用者にあります。 利用者は自身の Clover アカウントと API 認証情報を使って、このサーバーを実行します。以下については、利用者が単独で責任を負います。Clover の開発者向け/API 利用規約および商標使用ポリシーの遵守、トークンの保護、アクセスするデータに関するデータ保護（GDPR/CCPA など）および税務上の義務の履行。書き込みツールは実際の加盟店データを変更します。まずサンドボックスでテストし、最小権限のトークンを使用してください。
• カードデータなし、決済なし。 このサーバーは決済カードデータを一切扱いません（整形レイヤーでブロックされます）。また、意図的に決済の取得、返金、取消を行えないようになっています。PCI-DSS 対応ソリューションではありません。
• サードパーティ API。 このプロジェクトは、運用者の認証情報を使用して Clover の公開 REST API を呼び出すだけであり、Clover SDK や独自コードは同梱していません。Clover はいつでも API を変更または制限できるため、機能が動作しなくなる場合があります。

ライセンス

MIT — LICENSE を参照してください。