How do I use clover-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@clover-mcp show me today's sales summary" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

clover-mcp

by SBolivarLoL

Overview Schema Source Related Servers Discussions Admin

Python

Hybrid

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.

Related MCP server: mcp-loyverse

Tools

Tool	Kind	Notes
`get_merchant_info` / `get_merchant_properties`	read	profile + POS config (banking fields never returned)
`get_sales_summary`	read	aggregated window (see Sales summary semantics)
`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)
`list_payments` / `list_refunds` / `list_credits` / `list_tenders`	read	payments, refunds, credits, tender types
`list_orders` / `get_order` / `list_open_orders` / `list_order_types`	read	order history + detail
`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
`list_categories` / `list_modifiers` / `list_taxes` / `list_item_groups` / `list_attributes` / `list_tags` / `list_discounts`	read	catalog structure
`list_tip_suggestions` / `get_default_service_charge`	read	tip presets + service-charge config
`list_devices` / `list_opening_hours` / `list_cash_events`	read	terminals, hours, cash-drawer log
`get_top_items`	read	best-sellers by units in a window
`list_employees` / `get_employee` / `list_shifts` / `list_active_shifts` / `list_roles`	read	PINs never returned (`EMPLOYEES_R`)
`search_customers` / `get_customer`	read	cards never returned
`whoami`	read	multi-tenant identity diagnostic (no secrets)
`summarize_sales` / `inventory_reorder_suggestions` / `detect_sales_anomalies` / `suggest_item_categories` / `draft_customer_message`	AI	reason via your client's model; read-only suggestions
`create_customer` / `update_customer`	write	dup-check + `dry_run`; update confirms via elicitation
`create_item` / `create_category` / `create_order` / `add_line_item`	write	guarded: `dry_run` + confirm before writing
`set_item_price_cents` / `set_item_stock_quantity` / `update_item_name`	write	optimistic-lock pre-check, bounds, `dry_run`
`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
`create_modifier_group` / `create_modifier` / `create_tag`	write	dup-guard (group/tag) or parent pre-check (modifier); guarded: `dry_run` + confirm before writing

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:

Variable	Description
`CLOVER_MERCHANT_ID`	Your Clover merchant ID
`CLOVER_ACCESS_TOKEN`	Your Clover API access token

Optional:

Variable	Default	Description
`CLOVER_REGION`	`na`	`na`, `eu`, or `la`
`CLOVER_SANDBOX`	`false`	`true` to use the Clover sandbox
`CLOVER_AUTH_MODE`	`token`	`token` or `oauth_refresh`
`CLOVER_READ_ONLY`	`false`	Refuse every write before making a Clover request
`CLOVER_WRITE_LIMIT_COUNT`	`10`	Maximum writes per safety window; `0` disables, negative values are rejected
`CLOVER_WRITE_LIMIT_WINDOW_S`	`300`	Positive write-safety window in seconds

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:

Permission	Used by
`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`	…also `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` (optional)
`MERCHANT_R`	…also `list_devices`, `list_tenders`, `list_order_types`, `list_opening_hours`, `list_cash_events`, `list_tip_suggestions`, `get_default_service_charge`

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:

FastMCP Cloud / Horizon (easiest): deploy with entrypoint server.py:mcp, enable the platform's built-in auth, and set single-merchant Clover env vars. The platform handles OAuth, HTTPS, and transport — no IdP setup, and do not set CLOVER_TRANSPORT/CLOVER_AUTH_* (that path needs an IdP and will fail).
Self-host: use server.py:create_server, which makes clover-mcp an OAuth 2.1 resource server (validates your IdP's JWTs, publishes Protected Resource Metadata per RFC 9728, routes by token claim) and refuses to start without an IdP so it can't run open.

Full setup for both in docs/DEPLOY.md. How SSO/SAML, SCIM, audit, and multi-tenant authorization fit: docs/enterprise-identity.md.

Sales summary semantics

get_sales_summary makes the accounting explicit so the LLM can explain it:

Gross = sum of result=SUCCESS payment amounts. FAIL/AUTH/uncaptured PRE_AUTH are excluded.
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.
Tips and taxes are broken out as their own line items.
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.
Offline payments are included; a note flags the window when any are present.
Currency comes from the merchant record, never defaulted.
Windows longer than 90 days are split and concatenated transparently.

Development

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

Correctness eval + latency/load benchmark against a sandbox: uv run python scripts/benchmark.py — methodology, results, and failure analysis in docs/eval.md.

Architecture (diagrams + module map): docs/ARCHITECTURE.md. Run a 5-minute demo: uv run python scripts/demo.py (or the runbook in docs/DEMO.md).

Observability

All observability output goes to stderr (stdout carries the MCP stdio protocol).

Audit logging (on by default) — every write emits one structured JSON line: {"ts":"2026-07-02T…Z","audit":"write","method":"PUT","path":"/items/…","status":200,"merchant":"…"}. The UTC ts records when; in multi-tenant mode a tenant field records who. No request bodies or secrets. Disable with CLOVER_AUDIT_LOG=false.
Latency logging — set CLOVER_LATENCY_LOG=true to emit a latency_ms line per Clover HTTP call.
Distributed tracing (optional) — install the OpenTelemetry extra and point it at your collector; every Clover call becomes a span. Without it, tracing is a zero-cost no-op (no dependency added):
```
uv pip install -e ".[otel]"
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
export OTEL_SERVICE_NAME=clover-mcp
```

Security

See SECURITY.md for the vulnerability disclosure policy.

Legal & disclaimer

This is not legal advice. The notes below describe the project's intent and the operator's responsibilities.

Not affiliated. This is an independent, community project. It is not affiliated with, endorsed by, or sponsored by Clover Network, LLC or Fiserv, Inc. "Clover" and related marks are trademarks of their respective owners and are used here only nominatively — to state that this software interoperates with the Clover REST API. No Clover logos or branding are used.
No warranty / no liability. The software is provided "AS IS" under the MIT License, without warranty of any kind. The authors are not liable for any claim, damage, or loss arising from its use — including incorrect data, unintended writes, downtime, or API changes outside the authors' control.
You operate it; you're responsible. You run this server with your own Clover account and API credentials. You are solely responsible for: complying with Clover's developer/API terms and trademark-usage policy; safeguarding your tokens; and meeting any data-protection (e.g. GDPR/CCPA) and tax obligations for data you access. The write tools modify live merchant data — test in the sandbox first and use least-privilege tokens.
No card data, no payments. The server never handles payment card data (the shaping layer blocks it) and deliberately cannot capture payments, refund, or void. It is not a PCI-DSS solution.
Third-party API. This project only calls Clover's public REST API using the operator's credentials; it bundles no Clover SDK or proprietary code. Clover may change or restrict its API at any time, which may break functionality.

License

MIT — see LICENSE.

Available Tools

56 tools

add_line_itemA

Modifies merchant data. Add a catalog item as a line item to an order.

Name/price are copied from the catalog item. Previews on dry_run; confirms via MCP elicitation or confirm=True before writing. Requires ORDERS_W. No payment.

Inputs: item_id (required), order_id (required), confirm, dry_run. Returns: object

apply_order_discountA

DestructiveIdempotent

Modifies merchant data. Apply an order-level discount.

Exactly one of percentage (1-100), amount_cents (1-100_000_000, positive — Clover requires a negative amount on the wire, this tool negates it for you), or catalogue_discount_id must be given. Catalogue discounts are resolved client-side (name + percentage/amount fetched from list_discounts and sent inline). Previews on dry_run (includes current discounts + a client-computed line-item subtotal — Clover has no computed order total); confirms via MCP elicitation or confirm=True before writing. Requires ORDERS_W.

Inputs: order_id (required), name, confirm, dry_run, +3 more. Returns: object

create_categoryA

Modifies merchant data. Create a new inventory category.

Previews on dry_run; confirms via your client's prompt (MCP elicitation) or confirm=True before writing. Requires INVENTORY_W.

Inputs: name (required), confirm, dry_run. Returns: object

create_customerA

Modifies merchant data. Create a new customer record in Clover.

Idempotency guard: searches for an existing customer with the same email or phone before creating. If a match is found and confirm_duplicate is False, the call is refused and the existing match is returned.

dry_run=True returns the would-be POST payload without sending it. Requires CUSTOMERS_R (duplicate check) and CUSTOMERS_W (write).

Inputs: last_name (required), first_name (required), email, phone, +3 more. Returns: object

create_itemA

Modifies merchant data. Create a new inventory item (name + price in cents).

Bounds 0–100_000_000 cents. Previews on dry_run; confirms via MCP elicitation or confirm=True before writing. Requires INVENTORY_W.

Inputs: name (required), price_cents (required), confirm, dry_run. Returns: object

create_modifierA

Modifies merchant data. Create a new modifier within a modifier group.

Pre-check: verifies the modifier group exists (404 -> clear error). Bounds: 0 <= price_cents <= 100_000_000. Previews on dry_run; confirms via MCP elicitation or confirm=True before writing. Requires INVENTORY_W.

Inputs: name (required), price_cents (required), modifier_group_id (required), confirm, +1 more. Returns: object

create_modifier_groupA

Modifies merchant data. Create a new modifier group (e.g. "Milk options").

Duplicate guard: refuses if a group with the same name (case-insensitive) already exists. Previews on dry_run; confirms via MCP elicitation or confirm=True before writing. Requires INVENTORY_W.

Inputs: name (required), confirm, dry_run. Returns: object

create_orderA

Modifies merchant data. Create a new open order (no line items, no payment).

Previews on dry_run; confirms via MCP elicitation or confirm=True before writing. Add items with add_line_item. Requires ORDERS_W.

Inputs: note, confirm, dry_run. Returns: object

create_tagA

Modifies merchant data. Create a new tag/label used to group items.

Duplicate guard: refuses if a tag with the same name (case-insensitive) already exists. Previews on dry_run; confirms via MCP elicitation or confirm=True before writing. Requires INVENTORY_W.

Inputs: name (required), confirm, dry_run. Returns: object

detect_sales_anomaliesA

Read-only

AI: flag unusual refund / discount / sales patterns in a window (default: today).

Read-only analysis. Needs a sampling-capable client (graceful fallback otherwise). Requires PAYMENTS_R and ORDERS_R.

Inputs: date_to, date_from. Returns: object

draft_customer_messageA

Read-only

AI: draft a customer message (promo / win-back / thank-you) for the given intent.

Returns a DRAFT only — never sends anything. Needs a sampling-capable client (graceful fallback otherwise). Requires CUSTOMERS_R.

Inputs: intent (required), customer_id (required). Returns: object

get_customerA

Read-only

Return a single customer by ID.

Pass include=["addresses"] or include=["orders"] to opt in to optional fields. Cards are never returned. Requires CUSTOMERS_R.

Inputs: customer_id (required), include. Returns: object

get_default_service_chargeA

Read-only

Return the merchant's default service charge configuration (name, enabled, percentage). Requires MERCHANT_R.

Inputs: no named parameters. Returns: object

get_employeeA

Read-only

Return a single employee by ID (PINs never returned). Requires EMPLOYEES_R.

Inputs: employee_id (required). Returns: object

get_itemA

Read-only

Return a single inventory item by ID, including stock quantity.

Pass include=["modifier_groups"], ["tax_rates"], ["categories"], and/or ["tags"] to opt in to those association details. Requires INVENTORY_R.

Inputs: item_id (required), include. Returns: object

get_merchant_infoA

Read-only

Return key information about this Clover merchant.

Includes name, address, currency, timezone, country, and business type. Also primes the internal currency and timezone cache used by all other tools.

Inputs: no named parameters. Returns: object

get_merchant_propertiesA

Read-only

Return the merchant's POS configuration (currency, tips, stock tracking, closeout, locale, support contacts). Banking/account fields are never returned. Requires MERCHANT_R.

Inputs: no named parameters. Returns: object

get_orderA

Read-only

Fetch a single order by ID, including line items and payment summary.

Expands lineItems and payments only. Customer card data never expanded. Returns a 404 error if the order_id does not exist. This tool is read-only.

Inputs: order_id (required). Returns: object

get_sales_by_employeeA

Read-only

Return gross sales grouped by employee for a date window (default: today).

Requires PAYMENTS_R; employee name enrichment additionally requires EMPLOYEES_R (degrades to IDs-only with a note if not granted).

Inputs: date_to, date_from. Returns: object

get_sales_by_hourA

Read-only

Return gross sales bucketed by local hour-of-day for a single day (default: today).

Buckets use the merchant's local timezone, falling back to UTC with a note if unavailable. Requires PAYMENTS_R.

Inputs: date. Returns: object

get_sales_summaryA

Read-only

Return an aggregated sales summary for the given date window.

Defaults to today (UTC) when no dates are supplied. Uses 90-day chunking so multi-month or full-year queries work transparently (emits progress logs when more than one window is scanned).

Rules: only result=SUCCESS payments counted; voids/refunds reported separately; tips, taxes broken out; offline payments flagged; currency from merchant record. This tool does NOT support payment capture, refund, or void actions.

Inputs: date_to, date_from. Returns: object

get_tips_by_employeeA

Read-only

Return a tip-out sheet: tips collected grouped by employee (default: today).

Requires PAYMENTS_R; employee name enrichment additionally requires EMPLOYEES_R (degrades to IDs-only with a note if not granted).

Inputs: date_to, date_from. Returns: object

get_top_itemsA

Read-only

Return the best-selling items in a date window, ranked by units sold.

Defaults to today (UTC); 90-day chunked. Each line item counts as one unit. Requires ORDERS_R.

Inputs: top_n, date_to, date_from. Returns: object

inventory_reorder_suggestionsA

Read-only

AI: prioritized reorder list — low-stock items crossed with sales velocity.

Read-only suggestion. Needs a sampling-capable client (graceful fallback otherwise). Requires INVENTORY_R and ORDERS_R.

Inputs: date_to, date_from, threshold. Returns: object

list_active_shiftsA

Read-only

Return currently open shifts (clocked in, not out) across all employees. Requires EMPLOYEES_R.

Inputs: no named parameters. Returns: object

list_attributesA

Read-only

Return item attributes (variant axes like Size/Color) with options. Requires INVENTORY_R.

Inputs: no named parameters. Returns: object

list_cash_eventsA

Read-only

Return recent cash-drawer events (paid in/out, no-sale, deposits).

Capped at limit (default 50, max 500). Requires MERCHANT_R.

Inputs: limit. Returns: object

list_creditsA

Read-only

Return the merchant's credits (store/account-credit adjustments, up to 1000).

Element shape is unverified (sandbox has none provisioned) — shaped conservatively. Requires PAYMENTS_R.

Inputs: no named parameters. Returns: object

list_devicesA

Read-only

Return the merchant's Clover devices/terminals. Requires MERCHANT_R.

Inputs: no named parameters. Returns: object

list_discountsA

Read-only

Return the merchant's discount catalogue (fixed-amount or percentage). Requires INVENTORY_R.

Inputs: no named parameters. Returns: object

list_employeesA

Read-only

Return a page of employees (PINs never returned). Requires EMPLOYEES_R.

Inputs: limit, offset. Returns: object

list_item_groupsA

Read-only

Return item groups (sets of item variants, e.g. size/color). Requires INVENTORY_R.

Inputs: no named parameters. Returns: object

list_itemsA

Read-only

Return a page of inventory items. Filter by name (query) or category (category_id).

Requires INVENTORY_R. fields: optional list of field names to keep (narrows the response; cannot widen past the allowlist).

Inputs: limit, query, fields, offset, +1 more. Returns: object

list_low_stock_itemsA

Read-only

Return all items whose stock quantity is at or below threshold.

Items with no stock tracking are excluded. Requires INVENTORY_R.

Inputs: threshold. Returns: object

list_modifiersA

Read-only

Return all modifier groups with their modifiers. Requires INVENTORY_R.

Inputs: no named parameters. Returns: object

list_opening_hoursA

Read-only

Return the merchant's opening-hours sets (per-day time ranges). Requires MERCHANT_R.

Inputs: no named parameters. Returns: object

list_open_ordersA

Read-only

Return all currently open orders for this merchant (up to 200).

Convenience wrapper — no date filter, state=open only. Customer card data is never included. This tool is read-only.

Inputs: no named parameters. Returns: result

list_ordersA

Read-only

List orders within an optional date window and/or state filter (default: today, limit 50).

state: open | paid | refunded | partially_refunded (omit for all states). Customer card data is never included. This tool is read-only. fields: optional list of field names to keep (narrows the response; cannot widen past the allowlist).

Inputs: limit, state, fields, date_to, +1 more. Returns: result

list_order_typesA

Read-only

Return the merchant's order types (Dine In, Take Out, …). Requires MERCHANT_R.

Inputs: no named parameters. Returns: object

list_paymentsA

Read-only

List payments within an optional date window (default: today, limit 50).

Only result=SUCCESS payments. Card transaction details never included. fields: optional list of field names to keep (narrows the response; cannot widen past the allowlist). This tool does NOT support payment capture, refund, or void actions.

Inputs: limit, fields, date_to, date_from. Returns: result

list_refundsA

Read-only

List refunds within an optional date window (default: today, limit 50).

Clover refunds are separate objects with a positive amount (cents), not negative payments. Card/transaction detail is never included. Requires PAYMENTS_R. This tool does NOT issue refunds.

Inputs: limit, date_to, date_from. Returns: result

list_rolesA

Read-only

Return the merchant's employee roles (name + system role category). Requires EMPLOYEES_R.

Inputs: no named parameters. Returns: object

list_shiftsA

Read-only

List shifts, optionally by employee and/or date window. Requires EMPLOYEES_R.

Without employee_id, aggregates shifts across all employees.

Inputs: date_to, date_from, employee_id. Returns: object

list_taxesA

Read-only

Return the merchant's tax rates (raw rate + computed percent). Requires INVENTORY_R.

Inputs: no named parameters. Returns: object

list_tendersA

Read-only

Return the merchant's tender types (payment methods: cash, credit, custom). Requires MERCHANT_R.

Inputs: no named parameters. Returns: object

list_tip_suggestionsA

Read-only

Return the merchant's tip-suggestion presets (percentage or flat amount). Requires MERCHANT_R.

Inputs: no named parameters. Returns: object

search_customersA

Read-only

Search customers by full name (query), phone, or email.

Cards are never returned. Requires CUSTOMERS_R. fields: optional list of field names to keep (narrows the response; cannot widen past the allowlist).

Inputs: email, limit, phone, query, +1 more. Returns: object

set_item_price_centsA

DestructiveIdempotent

Modifies merchant data. Set an item's price (in cents, absolute value).

Optimistic lock: refuses the write unless the item's current price equals expected_current_price_cents (prevents stale-context overwrites). Bounds: 0 <= new_price_cents <= 100_000_000. dry_run=True previews the PUT body (still performs one read to fetch current price/name) and never writes. Requires INVENTORY_R and INVENTORY_W.

Inputs: item_id (required), new_price_cents (required), expected_current_price_cents (required), dry_run. Returns: object

set_item_stock_quantityA

DestructiveIdempotent

Modifies merchant data. Set an item's stock to an ABSOLUTE quantity (not a delta).

Optimistic lock: refuses unless current stock equals expected_current_quantity. Bounds: 0 <= new_quantity <= 1_000_000. dry_run=True previews the PUT body (still performs one read to fetch current stock) and never writes. Requires INVENTORY_R and INVENTORY_W.

Inputs: item_id (required), new_quantity (required), expected_current_quantity (required), dry_run. Returns: object

suggest_item_categoriesA

Read-only

AI: suggest categories for uncategorized items from the merchant's own taxonomy.

Suggestion only — applying a category is a separate, confirmed write. Needs a sampling-capable client (graceful fallback otherwise). Requires INVENTORY_R.

Inputs: limit. Returns: object

summarize_salesA

Read-only

AI: plain-language sales briefing for a date window (default: today).

Gathers the sales summary + top items, then asks your client's model to write a short narrative. Read-only suggestion. Needs a sampling-capable client; if yours can't sample, returns the raw data with a note. Requires ORDERS_R/PAYMENTS_R.

Inputs: date_to, date_from. Returns: object

update_customerA

DestructiveIdempotent

Modifies merchant data. Update a customer's name and/or marketing opt-in.

Only the fields you pass change. Previews on dry_run; confirms via MCP elicitation or confirm=True before writing. Requires CUSTOMERS_W.

Inputs: customer_id (required), confirm, dry_run, last_name, +2 more. Returns: object

update_item_nameA

DestructiveIdempotent

Modifies merchant data. Rename an inventory item (price/other fields preserved).

Optimistic lock: refuses unless the item's current name equals expected_current_name. Bounds: non-empty, <= 127 characters. dry_run=True previews the POST body (still performs one read) and never writes. Requires INVENTORY_R and INVENTORY_W.

Inputs: item_id (required), new_name (required), expected_current_name (required), confirm, +1 more. Returns: object

whoamiA

Read-only

Diagnostic: who is this request authenticated as, and is a Clover tenant mapped to them?

Returns the authenticated identity, the names of available token claims (never their values), scopes, and whether a tenant is provisioned — no Clover data and no secrets. Use it when setting up multi-tenant to discover which identity claim your platform (e.g. FastMCP Cloud / Horizon) actually provides, so you can key CLOVER_TENANTS_JSON correctly.

Inputs: no named parameters. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.8/5.0

Scored 2026-08-07 02:45 across 56 tools

Disambiguation5/5

Each tool targets a distinct resource or action, with clear boundaries even among the many list_* tools (orders, payments, refunds, items, categories, etc.). The only potential overlap, list_open_orders versus list_orders with a state filter, is explicitly documented as a convenience wrapper.

Naming Consistency4/5

Most tools follow a consistent verb_noun pattern (list_, get_, create_, set_, update_). Minor deviations include 'whoami' (single word), 'inventory_reorder_suggestions' (noun phrase instead of verb-first), and the mix of set_item_* vs. update_item_name.

Tool Count1/5

With 56 tools, the server far exceeds the threshold for an appropriate count. Even for a broad POS integration, 50+ tools is an extreme mismatch and will overwhelm agents with too many options.

Completeness2/5

The server provides extensive read-only reporting and some inventory/customer writes, but it lacks critical lifecycle operations: no payment capture/refund/void, no update/delete for orders or inventory items, and no order closing. Creates exist for orders and items but no way to complete or remove them, leaving obvious dead ends.

Maintenance

ActivitySlowing

ResponsivenessNo recent community issues

Resources

Related MCP Connectors

mcp-server
io.klokin
MCP server exposing klokin time-tracking operations (employees, time entries, stores) to AI clients.
Workplace & Productivity Project Management
2
https://mcp.klokin.io
Artificial Wit AI
com.artificialwit
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
ERP Systems CRM Knowledge & Memory
2
https://api.artificialwit.com/mcp
OneSchema MCP Server
co.oneschema
MCP server that lets AI assistants use all OneSchema features exposed via the public API.
Data Platforms App Automation
1
https://api.oneschema.co/mcp
MerchantFlowA
ai.merchantflow
MerchantFlow is a hosted, read-only ecommerce analytics MCP server for Shopify and WooCommerce. It gives AI assistants tenant-scoped access to revenue, profit and loss, product and SKU profitability, COGS coverage, fulfillment costs, advertising spend, ROAS, marketing performance, cohorts, LTV, and business valuation across connected commerce and marketing platforms. Connect with OAuth over Streamable HTTP. No local server installation is required.
E-commerce & Retail Finance Marketing
1
https://merchantflow.ai/api/mcp

Related MCP Servers

revolut-merchant-mcp
Payments & Billing E-commerce & Retail
Sherman-Studio
A
license
B
quality
B
maintenance
MCP server for the Revolut Merchant API, enabling AI assistants to read and manage customers, orders, subscriptions, and plans. Supports sandbox and production with safe defaults.
Updated 5 months ago (2026-06-19 09:37 UTC)
8
MIT
mcp-loyverse
E-commerce & Retail Finance
Novigante
A
license
A
quality
D
maintenance
A local-first, read-only MCP server for the Loyverse POS API that lets AI assistants query receipts, items, employees, customers, stores, and sales analytics — built for secure local use with Personal Access Tokens.
Updated 8 months ago (2026-03-02 21:34 UTC)
15
13 npm
Apache 2.0
MCP API Tool Demo
Customer Data Platforms Search
jordansilly77-stack
F
license
Not graded
quality
D
maintenance
Demo MCP server that exposes order and customer data as read-only tools for AI assistants, simulating a business API or internal data source.
Updated 5 months ago (2026-06-26 04:55 UTC)
-
qualys-pci-mcp
Security Penetration Testing
RobotDisco
A
license
A
quality
D
maintenance
A read-only MCP server for the Qualys PCI Merchant API that lets LLM assistants answer questions about PCI compliance posture, such as which hosts are failing PCI or listing high findings.
Updated 3 months ago (2026-08-05 13:04 UTC)
7
Apache 2.0

clover-mcp

What it can do

Tools

Install

Configuration

Auth modes

Claude Desktop setup

Cursor setup

Required Clover permissions

Remote / hosted (v2)

Sales summary semantics

Development

Observability

Security

Legal & disclaimer

License

Available Tools

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

revolut-merchant-mcp

mcp-loyverse

MCP API Tool Demo

qualys-pci-mcp