{
  "markdown": "# clover-mcp\n\nMCP server for the Clover POS REST API — gives AI assistants (Claude, Cursor, etc.) read and safe-write access to a Clover merchant's sales, inventory, orders, and customers.\n\n[![PyPI](https://img.shields.io/pypi/v/clover-mcp)](https://pypi.org/project/clover-mcp/)\n[![Python versions](https://img.shields.io/pypi/pyversions/clover-mcp)](https://pypi.org/project/clover-mcp/)\n[![License: MIT](https://img.shields.io/pypi/l/clover-mcp)](LICENSE)\n\n<!-- mcp-name: io.github.SBolivarLoL/clover-mcp -->\n\n> **Status:** v0.7.0 released; working tree (unreleased) — 56 tools, 6 prompts, both auth modes, 399 tests. Runs locally (stdio, single merchant) or remotely over HTTP with OAuth, single- or multi-tenant (see [docs/DEPLOY.md](docs/DEPLOY.md)). Endpoint contracts are sandbox-verified in [docs/endpoints.md](docs/endpoints.md).\n\n> ⚠️ **Independent project — not affiliated with, endorsed by, or sponsored by Clover Network, LLC or Fiserv, Inc.** \"Clover\" is a trademark of its respective owner and is used here only nominatively to describe interoperability. Provided **as is**, without warranty — see [Legal & disclaimer](#legal--disclaimer).\n\n## What it can do\n\n- Sales summaries, payment and refund reports\n- Inventory lookups and low-stock alerts\n- Order history and open-order inspection\n- Customer search and creation\n- Employee, shift, role, category, modifier, tax, tender, and device lookups; best-selling items\n- Pricing config lookups: discount catalogue, tip-suggestion presets, default service charge\n- Safe writes: update item prices, set stock quantities, create customers/items/categories/orders, add line items, update customers, rename items, apply order discounts, create modifier groups/modifiers/tags\n- AI tools (reason via your client's model — the server holds no LLM key): sales briefings, reorder suggestions, anomaly detection, category suggestions, customer-message drafts\n- Predefined prompt workflows: daily briefing, weekly sales report, inventory health check, end-of-day closeout, customer lookup, monthly tax summary\n\n**What it cannot do (by design):** process refunds, capture payments, void charges, delete records. Those stay in the Clover dashboard.\n\n## Tools\n\n| Tool | Kind | Notes |\n|---|---|---|\n| `get_merchant_info` / `get_merchant_properties` | read | profile + POS config (banking fields never returned) |\n| `get_sales_summary` | read | aggregated window (see [Sales summary semantics](#sales-summary-semantics)) |\n| `get_sales_by_employee` / `get_tips_by_employee` / `get_sales_by_hour` | read | employee attribution, tip-out, and merchant-local daypart reporting (`PAYMENTS_R`; employee names are best-effort) |\n| `list_payments` / `list_refunds` / `list_credits` / `list_tenders` | read | payments, refunds, credits, tender types |\n| `list_orders` / `get_order` / `list_open_orders` / `list_order_types` | read | order history + detail |\n| `list_items` / `get_item` / `list_low_stock_items` | read | inventory + stock; `get_item(include=[...])` opts in to `modifier_groups`/`tax_rates`/`categories`/`tags` association detail |\n| `list_categories` / `list_modifiers` / `list_taxes` / `list_item_groups` / `list_attributes` / `list_tags` / `list_discounts` | read | catalog structure |\n| `list_tip_suggestions` / `get_default_service_charge` | read | tip presets + service-charge config |\n| `list_devices` / `list_opening_hours` / `list_cash_events` | read | terminals, hours, cash-drawer log |\n| `get_top_items` | read | best-sellers by units in a window |\n| `list_employees` / `get_employee` / `list_shifts` / `list_active_shifts` / `list_roles` | read | PINs never returned (`EMPLOYEES_R`) |\n| `search_customers` / `get_customer` | read | cards never returned |\n| `whoami` | read | multi-tenant identity diagnostic (no secrets) |\n| `summarize_sales` / `inventory_reorder_suggestions` / `detect_sales_anomalies` / `suggest_item_categories` / `draft_customer_message` | AI | reason via your client's model; read-only suggestions |\n| `create_customer` / `update_customer` | write | dup-check + `dry_run`; update confirms via elicitation |\n| `create_item` / `create_category` / `create_order` / `add_line_item` | write | guarded: `dry_run` + confirm before writing |\n| `set_item_price_cents` / `set_item_stock_quantity` / `update_item_name` | write | optimistic-lock pre-check, bounds, `dry_run` |\n| `apply_order_discount` | write | exactly one of `percentage` / `amount_cents` / `catalogue_discount_id`; negates positive `amount_cents` to Clover's required negative wire value; catalogue path resolves name+value client-side; `dry_run` preview includes a client-computed line-item subtotal |\n| `create_modifier_group` / `create_modifier` / `create_tag` | write | dup-guard (group/tag) or parent pre-check (modifier); guarded: `dry_run` + confirm before writing |\n\nEvery tool carries MCP behaviour annotations (`readOnlyHint` / `destructiveHint` / `idempotentHint`) so clients can parallelize reads and prompt before writes.\n\n## Install\n\nPublished on [PyPI](https://pypi.org/project/clover-mcp/) — no clone needed:\n\n```bash\nuvx clover-mcp          # run directly (recommended)\n# or\npip install clover-mcp  # then launch with: clover-mcp\n```\n\nFrom source (for development):\n\n```bash\ngit clone https://github.com/SBolivarLoL/clover-mcp-server\ncd clover-mcp-server\nuv pip install -e .\n```\n\n## Configuration\n\nCopy `.env.example` to `.env` and fill in your values:\n\n```bash\ncp .env.example .env\n```\n\nRequired:\n\n| Variable | Description |\n|---|---|\n| `CLOVER_MERCHANT_ID` | Your Clover merchant ID |\n| `CLOVER_ACCESS_TOKEN` | Your Clover API access token |\n\nOptional:\n\n| Variable | Default | Description |\n|---|---|---|\n| `CLOVER_REGION` | `na` | `na`, `eu`, or `la` |\n| `CLOVER_SANDBOX` | `false` | `true` to use the Clover sandbox |\n| `CLOVER_AUTH_MODE` | `token` | `token` or `oauth_refresh` |\n| `CLOVER_READ_ONLY` | `false` | Refuse every write before making a Clover request |\n| `CLOVER_WRITE_LIMIT_COUNT` | `10` | Maximum writes per safety window; `0` disables, negative values are rejected |\n| `CLOVER_WRITE_LIMIT_WINDOW_S` | `300` | Positive write-safety window in seconds |\n\n### Auth modes\n\n- **`token`** — paste a static access token. Works for sandbox and single-merchant production use. If the token expires, regenerate it in the Clover Developer Dashboard.\n- **`oauth_refresh`** — the server auto-refreshes on expiry and persists the new token pair to `CLOVER_TOKEN_STORE` (default: `~/.config/clover-mcp/tokens.json`, mode 0600). Clover refresh tokens are single-use, so the rotated pair is written back after each refresh. Run `scripts/get_sandbox_token.py` to obtain tokens — it writes them straight to the store, so you only set `CLOVER_AUTH_MODE`, `CLOVER_OAUTH_CLIENT_ID`, `CLOVER_OAUTH_CLIENT_SECRET`, and `CLOVER_MERCHANT_ID` in `.env` (no token values needed). Pasting `CLOVER_ACCESS_TOKEN` / `CLOVER_REFRESH_TOKEN` into `.env` still works as an alternative.\n\n> **Use a least-privilege token.** Grant only the permission scopes the tools you actually use require (see the table below). A read-only deployment needs no `*_W` scopes at all. Don't reuse a production token in sandbox or vice versa.\n\n## Claude Desktop setup\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"clover\": {\n      \"command\": \"uvx\",\n      \"args\": [\"clover-mcp\"],\n      \"env\": {\n        \"CLOVER_MERCHANT_ID\": \"your_merchant_id\",\n        \"CLOVER_ACCESS_TOKEN\": \"your_token\",\n        \"CLOVER_REGION\": \"na\"\n      }\n    }\n  }\n}\n```\n\n## Cursor setup\n\nAdd to `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` globally):\n\n```json\n{\n  \"mcpServers\": {\n    \"clover\": {\n      \"command\": \"uvx\",\n      \"args\": [\"clover-mcp\"],\n      \"env\": {\n        \"CLOVER_MERCHANT_ID\": \"your_merchant_id\",\n        \"CLOVER_ACCESS_TOKEN\": \"your_token\"\n      }\n    }\n  }\n}\n```\n\n## Required Clover permissions\n\nYour token must have the following Clover permission scopes:\n\n| Permission | Used by |\n|---|---|\n| `MERCHANT_R` | `get_merchant_info` |\n| `ORDERS_R` | `list_orders`, `get_order`, `list_open_orders` |\n| `PAYMENTS_R` | `list_payments`, `list_refunds`, `list_credits`, `get_sales_summary`, `get_sales_by_employee`, `get_tips_by_employee`, `get_sales_by_hour` |\n| `ORDERS_R` | …also `get_top_items` |\n| `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` |\n| `INVENTORY_W` | `set_item_price_cents`, `set_item_stock_quantity`, `create_item`, `create_category`, `update_item_name`, `create_modifier_group`, `create_modifier`, `create_tag` |\n| `ORDERS_W` | `create_order`, `add_line_item`, `apply_order_discount` |\n| `CUSTOMERS_R` | `search_customers`, `get_customer` |\n| `CUSTOMERS_W` | `create_customer`, `update_customer` |\n| `EMPLOYEES_R` | `list_employees`, `get_employee`, `list_shifts`, `list_active_shifts`, `list_roles` (optional) |\n| `MERCHANT_R` | …also `list_devices`, `list_tenders`, `list_order_types`, `list_opening_hours`, `list_cash_events`, `list_tip_suggestions`, `get_default_service_charge` |\n\nRead scopes (`*_R`) are probed at startup; the server **warns** about any missing ones (it no longer exits — a hosted server must still start) and the affected tools return a 403 when called. `EMPLOYEES_R` is optional. Write scopes (`*_W`) are **not** probed (a probe would mutate data) — a missing write scope surfaces as a 403 the first time you call that tool. Permission changes on a Clover app require the merchant to reinstall the app.\n\n## Remote / hosted (v2)\n\nBy default this runs locally over stdio for a single merchant. To run it remotely:\n\n- **FastMCP Cloud / Horizon (easiest):** deploy with entrypoint `server.py:mcp`,\n  enable the platform's built-in auth, and set single-merchant Clover env vars.\n  The platform handles OAuth, HTTPS, and transport — no IdP setup, and do **not**\n  set `CLOVER_TRANSPORT`/`CLOVER_AUTH_*` (that path needs an IdP and will fail).\n- **Self-host:** use `server.py:create_server`, which makes clover-mcp an OAuth\n  2.1 **resource server** (validates your IdP's JWTs, publishes Protected Resource\n  Metadata per RFC 9728, routes by token claim) and **refuses to start without an\n  IdP** so it can't run open.\n\nFull setup for both in **[docs/DEPLOY.md](docs/DEPLOY.md)**. How SSO/SAML, SCIM,\naudit, and multi-tenant authorization fit: **[docs/enterprise-identity.md](docs/enterprise-identity.md)**.\n\n## Sales summary semantics\n\n`get_sales_summary` makes the accounting explicit so the LLM can explain it:\n\n- **Gross** = sum of `result=SUCCESS` payment amounts. `FAIL`/`AUTH`/uncaptured `PRE_AUTH` are excluded.\n- **Refunds** come from the dedicated `/refunds` endpoint (Clover refunds are separate objects with a positive amount, not negative payments). **Voids** are counted from voided payments. Both are reported separately (`refund_count`/`refund_amount`, `void_count`) — never netted into `payment_count`. `net_sales = gross_sales - refund_amount`.\n- **Tips and taxes** are broken out as their own line items.\n- **Service charges** are *not* reported separately: Clover exposes them on the order only as a percentage (no computed amount), and what customers actually paid is already in `gross_sales` via payment totals.\n- **Offline payments** are included; a `note` flags the window when any are present.\n- **Currency** comes from the merchant record, never defaulted.\n- Windows longer than 90 days are split and concatenated transparently.\n\n## Development\n\n```bash\nuv pip install -e \".[dev]\"\npytest\nruff check src/ tests/ scripts/\nruff format --check src/ tests/ scripts/\nmypy src/clover_mcp/\n```\n\nCorrectness eval + latency/load benchmark against a sandbox:\n`uv run python scripts/benchmark.py` — methodology, results, and failure analysis\nin [docs/eval.md](docs/eval.md).\n\nArchitecture (diagrams + module map): [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).\nRun a 5-minute demo: `uv run python scripts/demo.py` (or the runbook in\n[docs/DEMO.md](docs/DEMO.md)).\n\n## Observability\n\nAll observability output goes to **stderr** (stdout carries the MCP stdio protocol).\n\n- **Audit logging** (on by default) — every write emits one structured JSON line:\n  `{\"ts\":\"2026-07-02T…Z\",\"audit\":\"write\",\"method\":\"PUT\",\"path\":\"/items/…\",\"status\":200,\"merchant\":\"…\"}`.\n  The UTC `ts` records when; in multi-tenant mode a `tenant` field records who.\n  No request bodies or secrets. Disable with `CLOVER_AUDIT_LOG=false`.\n- **Latency logging** — set `CLOVER_LATENCY_LOG=true` to emit a `latency_ms` line\n  per Clover HTTP call.\n- **Distributed tracing (optional)** — install the OpenTelemetry extra and point it\n  at your collector; every Clover call becomes a span. Without it, tracing is a\n  zero-cost no-op (no dependency added):\n\n  ```bash\n  uv pip install -e \".[otel]\"\n  export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317\n  export OTEL_SERVICE_NAME=clover-mcp\n  ```\n\n## Security\n\nSee [SECURITY.md](SECURITY.md) for the vulnerability disclosure policy.\n\n## Legal & disclaimer\n\n> This is not legal advice. The notes below describe the project's intent and the\n> operator's responsibilities.\n\n- **Not affiliated.** This is an independent, community project. It is **not**\n  affiliated with, endorsed by, or sponsored by Clover Network, LLC or Fiserv, Inc.\n  \"Clover\" and related marks are trademarks of their respective owners and are used\n  here only **nominatively** — to state that this software interoperates with the\n  Clover REST API. No Clover logos or branding are used.\n- **No warranty / no liability.** The software is provided **\"AS IS\"** under the\n  [MIT License](LICENSE), without warranty of any kind. The authors are not liable\n  for any claim, damage, or loss arising from its use — including incorrect data,\n  unintended writes, downtime, or API changes outside the authors' control.\n- **You operate it; you're responsible.** You run this server with **your own**\n  Clover account and API credentials. You are solely responsible for: complying\n  with Clover's developer/API terms and trademark-usage policy; safeguarding your\n  tokens; and meeting any data-protection (e.g. GDPR/CCPA) and tax obligations for\n  data you access. The write tools **modify live merchant data** — test in the\n  sandbox first and use least-privilege tokens.\n- **No card data, no payments.** The server never handles payment card data (the\n  shaping layer blocks it) and deliberately cannot capture payments, refund, or\n  void. It is **not** a PCI-DSS solution.\n- **Third-party API.** This project only calls Clover's public REST API using the\n  operator's credentials; it bundles no Clover SDK or proprietary code. Clover may\n  change or restrict its API at any time, which may break functionality.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n",
  "bytes": 14809,
  "sha": "8d9a26fb9a2d5a5f301ba0ecd78be4a9125008f1cafdcf1929c9570468625763",
  "repo_slug": "sbolivarlol/clover-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_sbolivarlol_clover_mcp_51f774f8/readme"
}