mcpengine/servers/clover

Clover MCP Server

A comprehensive Model Context Protocol (MCP) server for the Clover POS platform, providing 50+ tools and 18 React applications for complete point-of-sale management.

Features

🛠️ 50+ MCP Tools

Orders Management (10 tools)

• clover_list_orders - List orders with filtering and pagination
• clover_get_order - Get order details with expanded data
• clover_create_order - Create new orders
• clover_update_order - Update existing orders
• clover_delete_order - Delete orders
• clover_add_line_item - Add items to orders
• clover_remove_line_item - Remove items from orders
• clover_add_order_discount - Apply discounts to orders
• clover_list_order_payments - List payments for an order
• clover_fire_order - Send order to kitchen

Inventory Management (11 tools)

• clover_list_items - List inventory items
• clover_get_item - Get item details
• clover_create_item - Create new items
• clover_update_item - Update existing items
• clover_delete_item - Delete items
• clover_list_categories - List item categories
• clover_create_category - Create new category
• clover_list_modifier_groups - List modifier groups
• clover_create_modifier - Create modifiers
• clover_list_item_stocks - List stock levels
• clover_update_item_stock - Update stock quantities

Customer Management (9 tools)

• clover_list_customers - List customers
• clover_get_customer - Get customer details
• clover_create_customer - Create new customer
• clover_update_customer - Update customer info
• clover_delete_customer - Delete customer
• clover_search_customers - Search by name/phone/email
• clover_list_customer_addresses - List customer addresses
• clover_add_customer_address - Add address to customer
• clover_list_customer_cards - List saved payment cards

Employee Management (10 tools)

• clover_list_employees - List employees
• clover_get_employee - Get employee details
• clover_create_employee - Create new employee
• clover_update_employee - Update employee info
• clover_delete_employee - Delete employee
• clover_list_employee_roles - List available roles
• clover_list_employee_shifts - List shifts for employee
• clover_create_shift - Create a shift
• clover_clock_in_employee - Clock in employee
• clover_clock_out_employee - Clock out employee

Payment Management (4 tools)

• clover_list_payments - List payments
• clover_get_payment - Get payment details
• clover_create_refund - Create refund
• clover_list_refunds - List refunds for payment

Merchant Settings (5 tools)

• clover_get_merchant - Get merchant information
• clover_update_merchant - Update merchant settings
• clover_list_devices - List POS devices
• clover_get_device - Get device details
• clover_list_tender_types - List payment methods

Discounts (5 tools)

• clover_list_discounts - List discounts
• clover_get_discount - Get discount details
• clover_create_discount - Create discount
• clover_update_discount - Update discount
• clover_delete_discount - Delete discount

Tax Management (5 tools)

• clover_list_tax_rates - List tax rates
• clover_get_tax_rate - Get tax rate details
• clover_create_tax_rate - Create tax rate
• clover_update_tax_rate - Update tax rate
• clover_delete_tax_rate - Delete tax rate

Reports & Analytics (4 tools)

• clover_sales_summary - Get sales summary for date range
• clover_revenue_by_item - Revenue breakdown by item
• clover_revenue_by_category - Revenue breakdown by category
• clover_employee_performance - Employee performance report

Cash Management (2 tools)

• clover_list_cash_events - List cash drawer events
• clover_get_cash_drawer - Get cash drawer status

📱 18 React MCP Apps

Order Management

• order-dashboard - Overview of order metrics and quick actions
• order-detail - Detailed order view with line items
• order-grid - Searchable grid of all orders

Inventory Management

• inventory-dashboard - Inventory metrics and quick actions
• inventory-detail - Item management with search
• category-manager - Category organization

Customer Management

• customer-detail - Detailed customer profile
• customer-grid - Customer directory with search

Employee Management

• employee-dashboard - Employee metrics and performance
• employee-schedule - Shift management and time tracking

Payments

• payment-history - Payment transactions and refunds

Reports & Analytics

• sales-dashboard - Sales metrics and trends
• revenue-by-item - Top performing items
• revenue-by-category - Category performance

Configuration

• discount-manager - Discount creation and management
• tax-manager - Tax rate configuration
• device-manager - POS device inventory

Cash Management

• cash-drawer - Cash drawer tracking and events

Installation

npm install
npm run build

Configuration

Set the following environment variables:

# Required
export CLOVER_MERCHANT_ID="your_merchant_id"

# One of these is required
export CLOVER_API_KEY="your_api_key"
# OR
export CLOVER_ACCESS_TOKEN="your_oauth_token"

# Optional (default: sandbox)
export CLOVER_ENVIRONMENT="sandbox"  # or "production"

Getting Clover Credentials

1. Sandbox Access: Sign up at https://sandbox.dev.clover.com/
2. API Key: Go to Setup → API Tokens in your Clover dashboard
3. OAuth Token: Implement OAuth2 flow for production apps

Usage

Running the Server

npm start

MCP Client Configuration

Add to your MCP client settings (e.g., Claude Desktop):

{
  "mcpServers": {
    "clover": {
      "command": "node",
      "args": ["/path/to/clover/dist/main.js"],
      "env": {
        "CLOVER_MERCHANT_ID": "your_merchant_id",
        "CLOVER_API_KEY": "your_api_key",
        "CLOVER_ENVIRONMENT": "sandbox"
      }
    }
  }
}

API Reference

Tool Usage Examples

List Orders

// List all open orders
await mcp.callTool('clover_list_orders', {
  filter: 'state=open',
  expand: 'lineItems,customers'
});

Create Order with Items

// Create order
const order = await mcp.callTool('clover_create_order', {
  state: 'open',
  title: 'Table 5'
});

// Add items
await mcp.callTool('clover_add_line_item', {
  orderId: order.id,
  itemId: 'ITEM_ID',
  unitQty: 2
});

Generate Sales Report

const summary = await mcp.callTool('clover_sales_summary', {
  startDate: Date.now() - 7 * 24 * 60 * 60 * 1000, // 7 days ago
  endDate: Date.now()
});

React App Resources

Apps are available as MCP resources:

const apps = await mcp.listResources();
// Returns: clover://app/order-dashboard, clover://app/inventory-detail, etc.

const appCode = await mcp.readResource('clover://app/order-dashboard');
// Returns the React component source

Architecture

src/
├── clients/
│   └── clover.ts          # Clover API client with pagination
├── tools/
│   ├── orders-tools.ts    # Order management tools
│   ├── inventory-tools.ts # Inventory tools
│   ├── customers-tools.ts # Customer tools
│   ├── employees-tools.ts # Employee tools
│   ├── payments-tools.ts  # Payment tools
│   ├── merchants-tools.ts # Merchant settings tools
│   ├── discounts-tools.ts # Discount tools
│   ├── taxes-tools.ts     # Tax tools
│   ├── reports-tools.ts   # Analytics tools
│   └── cash-tools.ts      # Cash management tools
├── ui/
│   └── react-app/         # 18 React MCP apps
├── types/
│   └── index.ts           # TypeScript type definitions
├── server.ts              # MCP server implementation
└── main.ts                # Entry point

Development

Build

npm run build

Watch Mode

npm run dev

API Coverage

This server implements the Clover REST API v3:

• Base URL (Sandbox): https://sandbox.dev.clover.com
• Base URL (Production): https://api.clover.com
• Documentation: https://docs.clover.com/docs

License

MIT

Contributing

Contributions welcome! Please ensure:

• TypeScript types are properly defined
• Tools follow the existing naming convention
• React apps use the standard UI patterns
• All tools include proper error handling

Support

For issues related to:

• This MCP server: Open a GitHub issue
• Clover API: Check https://docs.clover.com/
• MCP Protocol: See https://modelcontextprotocol.io/

---

Built with ❤️ for the MCPEngine ecosystem