@ibraheem4/clover-mcp v1.0.1

Clover MCP (Model Context Protocol) Server

A minimal MCP server for interacting with the Clover API using OAuth authentication.

Overview

This MCP server allows generative AI models and other clients to access your Clover merchant data using the Model Context Protocol. With this integration, models can:

• Retrieve merchant information
• List inventory items
• List orders
• Access individual items and orders

Quick Start

Using with Claude AI (Recommended)

1. Add this to your Claude MCP settings (usually in ~/.config/anthropic/claude.mcp.json):

{
  "mcpServers": {
    "clover": {
      "command": "npx",
      "args": ["-y", "@ibraheem4/clover-mcp"],
      "env": {
        "CLOVER_CLIENT_ID": "your-clover-client-id",
        "CLOVER_CLIENT_SECRET": "your-clover-client-secret",
        "CLOVER_BASE_URL": "https://apisandbox.dev.clover.com"
      },
      "disabled": false,
      "autoApprove": ["initiate_oauth_flow", "get_merchant_info", "list_inventory", "list_orders"]
    }
  }
}

2. Use it with Claude:

/mcp use clover

3. Start the OAuth flow in your conversation with Claude:

Can you help me connect to my Clover account?

Using via Command Line

You can run the MCP server directly:

# Install and run in one command
npx @ibraheem4/clover-mcp

# With credentials
CLOVER_CLIENT_ID=your-client-id CLOVER_CLIENT_SECRET=your-client-secret npx @ibraheem4/clover-mcp

Clover OAuth Setup

Before using this MCP server, you need to set up a Clover app:

1. Create a Clover developer account at developer.clover.com
2. Register a new app in the Clover Developer Dashboard
3. Configure your app with:
   • Site URL: http://localhost:4000/oauth-callback
   • Default OAuth Response: Code
4. Note your Client ID and Client Secret
5. Add these credentials to your environment or .env file

MCP Tools

The following tools are available via the MCP protocol:

Core Functionality

• get_oauth_status: Check if OAuth credentials are available
• initiate_oauth_flow: Start the OAuth flow to get access tokens
• get_merchant_info: Get information about the merchant
• list_inventory: List inventory items with optional filters
• list_orders: List orders with optional filters

Customer Management

• list_customers: List customers with optional filtering
• get_customer: Get details for a specific customer

Employee Management

• list_employees: List employees working for the merchant
• get_employee: Get details for a specific employee
• list_shifts: List employee shifts with optional filtering

Inventory and Catalog Management

• list_categories: List inventory categories
• list_modifiers: List item modifiers
• list_modifier_groups: List modifier groups for inventory items
• get_inventory_stock: Get current inventory stock levels

Pricing and Payment

• list_tenders: List payment tender types
• list_payments: List payments with optional filtering
• list_discounts: List available discounts
• list_tax_rates: List tax rates

Business Operations

• get_business_hours: Get merchant's business hours

Reporting and Analytics

• get_order_summary: Get order summary for reporting purposes
• get_sales_metrics: Get sales metrics and analytics with time-based grouping

Example Usage with Claude

Here are some example prompts you can use with Claude after connecting:

1. Connect to Clover:

   I'd like to connect to my Clover account.

2. Get Merchant Information:

   What information do you have about my Clover merchant account?
   What are my business hours?

3. Inventory Management:

   Show me the first 10 items in my inventory.
   What categories do I have set up in my inventory?
   Show me all the modifiers available for my menu items.
   List all my modifier groups.
   Check the current stock levels for my inventory.

4. Order Information:

   Can you list my most recent orders?
   Show me a summary of orders from last month.

5. Customer Data:

   Who are my recent customers?
   Search for a customer named "Smith" in my database.

6. Employee Management:

   List all employees who work at my store.
   Get details for my employee with ID "ABC123".
   Show me employee shifts from last week.

7. Pricing and Payment:

   What payment methods do we accept?
   Show me the payments we've received in the last week.
   List all the discounts we currently offer.
   What tax rates are configured in my system?

8. Financial Reports and Analytics:

   Give me a summary of our completed orders from June 1-15.
   What were our sales metrics for last month?
   What are our top selling items for the past 30 days?
   Give me a breakdown of our daily sales over the past week.

9. Business Insights:

   What trends do you see in our sales data over the past 3 months?
   Which employees worked the most hours last month?
   When are our busiest times based on order data?
   Compare our sales this month vs. last month.

Development

Local Installation

1. Clone this repository
2. Install dependencies:

   npm install

3. Set up your OAuth credentials:

   cp .env.example .env
   # Edit .env with your Clover OAuth credentials

4. Build the TypeScript code:

   npm run build

5. Start the MCP server:

   ./run.sh

Publishing Updates

To publish a new version to npm:

# Update version in package.json
npm version patch  # or minor, or major

# Build and publish
npm run build
npm publish

Troubleshooting

If you encounter OAuth problems:

1. Verify your Clover app is properly registered
2. Check that the Site URL in your app settings is set to http://localhost:4000/oauth-callback
3. Ensure your Client ID and Client Secret are correct
4. Make sure "Default OAuth Response" is set to "Code" in the developer dashboard
5. Try starting the OAuth flow again with initiate_oauth_flow

License

MIT