clover-mcp

MCP 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.

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). Endpoint contracts are sandbox-verified in docs/endpoints.md.

⚠️ 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.

What it can do

• Sales summaries, payment and refund reports
• Inventory lookups and low-stock alerts
• Order history and open-order inspection
• Customer search and creation
• Employee, shift, role, category, modifier, tax, tender, and device lookups; best-selling items
• Pricing config lookups: discount catalogue, tip-suggestion presets, default service charge
• 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
• 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
• Predefined prompt workflows: daily briefing, weekly sales report, inventory health check, end-of-day closeout, customer lookup, monthly tax summary

What it cannot do (by design): process refunds, capture payments, void charges, delete records. Those stay in the Clover dashboard.

Tools

Every tool carries MCP behaviour annotations (readOnlyHint / destructiveHint / idempotentHint) so clients can parallelize reads and prompt before writes.

Install

Published on PyPI — no clone needed:

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

From source (for development):

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

Configuration

Copy .env.example to .env and fill in your values:

cp .env.example .env

Required:

Optional:

Auth modes

• 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.
• 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.

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.

Claude Desktop setup

Add to ~/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 setup

Add to .cursor/mcp.json in your project (or ~/.cursor/mcp.json globally):

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

Required Clover permissions

Your token must have the following Clover permission scopes:

Read 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.

Remote / hosted (v2)

By default this runs locally over stdio for a single merchant. To run it remotely: