{"_id":"@dokdosolutions/clover-mcp","_rev":"6-d7af9590c3eb44223b231d52fe36d50d","name":"@dokdosolutions/clover-mcp","dist-tags":{"latest":"1.0.4"},"versions":{"1.0.0":{"name":"@dokdosolutions/clover-mcp","version":"1.0.0","_id":"@dokdosolutions/clover-mcp@1.0.0","maintainers":[{"name":"dokdosolutions","email":"dokdosolutions@gmail.com"}],"bin":{"clover-mcp":"dist/index.js"},"dist":{"shasum":"28ed95f15ff3ad2bc1c14332ddafcaa97f4133f5","tarball":"https://registry.npmjs.org/@dokdosolutions/clover-mcp/-/clover-mcp-1.0.0.tgz","fileCount":19,"integrity":"sha512-NDDEEIgVK512bSPMcSlF+TiZPr/34yzsU99nBG2CqcCoc9lJsubDY554CbsaFmFySEDOKdQ7+iEwVhu0jxZLnA==","signatures":[{"sig":"MEQCIBeT5P5BNAFAnXxIdMZwJdIsIG5xBOLJbHkXUqNv7lo4AiBip1rxfhGf7FoFAQv2FO725faMZF8s/OhqWag6nHNWyQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":112330},"main":"dist/index.js","type":"module","engines":{"node":">=20"},"gitHead":"943e6970b88b3d606743ecdaa5cd60af8fb7c042","scripts":{"dev":"tsx src/index.ts","test":"jest --config jest.config.cjs","build":"tsc","start":"node dist/index.js","inspector":"npx @modelcontextprotocol/inspector node dist/index.js","test:sandbox":"tsx scripts/run-tests.ts","prepublishOnly":"npm run build && npm test"},"_npmUser":{"name":"dokdosolutions","email":"dokdosolutions@gmail.com"},"_npmVersion":"10.9.7","description":"Model Context Protocol server for Clover POS — restaurant-focused AI integration by Dokdo Solutions","directories":{},"_nodeVersion":"22.22.2","dependencies":{"zod":"^3.23.0","axios":"^1.7.0","bottleneck":"^2.19.5","axios-retry":"^4.5.0","@modelcontextprotocol/sdk":"^1.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.0.0","jest":"^30.4.2","ts-jest":"^29.4.11","typescript":"^5.5.0","@types/jest":"^30.0.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/clover-mcp_1.0.0_1780718178186_0.3068231341785468","host":"s3://npm-registry-packages-npm-production"},"deprecated":"Package moved. See https://github.com/Ahreum-us/clover-mcp-server"},"1.0.1":{"name":"@dokdosolutions/clover-mcp","version":"1.0.1","_id":"@dokdosolutions/clover-mcp@1.0.1","maintainers":[{"name":"dokdosolutions","email":"dokdosolutions@gmail.com"}],"bin":{"clover-mcp":"dist/index.js"},"dist":{"shasum":"861ebb762d4f9ecbcfd9ab4a095f0cea6f1f7b1b","tarball":"https://registry.npmjs.org/@dokdosolutions/clover-mcp/-/clover-mcp-1.0.1.tgz","fileCount":19,"integrity":"sha512-eoHsXWsrbCfb5f4c0L+Gf5RaTR0X/svMSOvYM6mR4bCJF2A1rQKGuNml6JyZGCjGDkBMKbl1X3t5J9ozz5b4CA==","signatures":[{"sig":"MEQCIBSW9cK6E6t1cw6ot+gGDi8Ap/B8HBT1RlnXkHOS5i31AiARUBuw3AIRkaSWbA+MpT5nxjrm5akEUzit+Tyb5bI7/A==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":112716},"main":"dist/index.js","type":"module","engines":{"node":">=24"},"gitHead":"e871d2bc35aa157cdadd3d3b2402bec0f9479bb2","scripts":{"dev":"tsx src/index.ts","test":"jest --config jest.config.cjs","build":"tsc","start":"node dist/index.js","inspector":"npx @modelcontextprotocol/inspector node dist/index.js","test:sandbox":"tsx scripts/run-tests.ts","prepublishOnly":"npm run build && npm test"},"_npmUser":{"name":"dokdosolutions","email":"dokdosolutions@gmail.com"},"_npmVersion":"10.9.7","description":"Model Context Protocol server for Clover POS — restaurant-focused AI integration by Dokdo Solutions","directories":{},"_nodeVersion":"22.22.2","dependencies":{"zod":"^3.23.0","axios":"^1.7.0","bottleneck":"^2.19.5","axios-retry":"^4.5.0","@modelcontextprotocol/sdk":"^1.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.0.0","jest":"^30.4.2","ts-jest":"^29.4.11","typescript":"^5.5.0","@types/jest":"^30.0.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/clover-mcp_1.0.1_1780802409437_0.9818926118947549","host":"s3://npm-registry-packages-npm-production"},"deprecated":"Package moved. See https://github.com/Ahreum-us/clover-mcp-server"},"1.0.2":{"name":"@dokdosolutions/clover-mcp","version":"1.0.2","_id":"@dokdosolutions/clover-mcp@1.0.2","maintainers":[{"name":"dokdosolutions","email":"dokdosolutions@gmail.com"}],"bin":{"clover-mcp":"dist/index.js"},"dist":{"shasum":"987218537b1fcffb80a6a4c68e9572b1fb08f8f8","tarball":"https://registry.npmjs.org/@dokdosolutions/clover-mcp/-/clover-mcp-1.0.2.tgz","fileCount":19,"integrity":"sha512-PmooPc7upDvllbrbVPd9lE2MRdvpDi7DzErp/TzmrkGpZTD1sIZKC3lEVwEKJ+M+bdplTvXw+m14OJJ5DTf5+g==","signatures":[{"sig":"MEQCICjV8x6KR+47NHwoO29weE6VoN1ATFMQLgJ/Pnin/miCAiAbDIy31YUFz4gbqR9Z35uzamHS7wYqv6P+OFOiizY9aw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":112716},"main":"dist/index.js","type":"module","engines":{"node":">=24"},"gitHead":"997e8276b325288252a7c3657759d5505acc01c6","scripts":{"dev":"tsx src/index.ts","test":"jest --config jest.config.cjs","build":"tsc","start":"node dist/index.js","inspector":"npx @modelcontextprotocol/inspector node dist/index.js","test:sandbox":"tsx scripts/run-tests.ts","prepublishOnly":"npm run build && npm test"},"_npmUser":{"name":"dokdosolutions","email":"dokdosolutions@gmail.com"},"_npmVersion":"10.9.7","description":"Model Context Protocol server for Clover POS — restaurant-focused AI integration by Dokdo Solutions","directories":{},"_nodeVersion":"22.22.2","dependencies":{"zod":"^3.23.0","axios":"^1.7.0","bottleneck":"^2.19.5","axios-retry":"^4.5.0","@modelcontextprotocol/sdk":"^1.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.0.0","jest":"^30.4.2","ts-jest":"^29.4.11","typescript":"^5.5.0","@types/jest":"^30.0.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/clover-mcp_1.0.2_1780803479358_0.5327711709919574","host":"s3://npm-registry-packages-npm-production"},"deprecated":"Package moved. See https://github.com/Ahreum-us/clover-mcp-server"},"1.0.3":{"name":"@dokdosolutions/clover-mcp","version":"1.0.3","_id":"@dokdosolutions/clover-mcp@1.0.3","maintainers":[{"name":"dokdosolutions","email":"dokdosolutions@gmail.com"}],"bin":{"clover-mcp":"dist/index.js"},"dist":{"shasum":"b21db667297279101563ea3c3c944579447cbce8","tarball":"https://registry.npmjs.org/@dokdosolutions/clover-mcp/-/clover-mcp-1.0.3.tgz","fileCount":19,"integrity":"sha512-RSBVYu3hPRsseY9JuNkT+u+3UwPhvh1gZ8Zh0sUU+QbgrkGg4z8yFSJ3vKZFzSB70LpaIqXstTM3XP1FeDykBQ==","signatures":[{"sig":"MEUCICG+kxFKC+nNTURbAhOPagzrN6n23J9VsY2ZXBRcNiK1AiEAnnVgvWfnUaybuXp2zbuM5QBY809JBK3EZcNlbd6YF1Q=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":112798},"main":"dist/index.js","type":"module","engines":{"node":">=24"},"gitHead":"997e8276b325288252a7c3657759d5505acc01c6","mcpName":"io.github.dokdosolutions-us/lucky","scripts":{"dev":"tsx src/index.ts","test":"jest --config jest.config.cjs","build":"tsc","start":"node dist/index.js","inspector":"npx @modelcontextprotocol/inspector node dist/index.js","test:sandbox":"tsx scripts/run-tests.ts","prepublishOnly":"npm run build && npm test"},"_npmUser":{"name":"dokdosolutions","email":"dokdosolutions@gmail.com"},"_npmVersion":"10.9.7","description":"Model Context Protocol server for Clover POS — restaurant operations, menu management, inventory, analytics, and customer retention","directories":{},"_nodeVersion":"22.22.2","dependencies":{"zod":"^3.23.0","axios":"^1.7.0","bottleneck":"^2.19.5","axios-retry":"^4.5.0","@modelcontextprotocol/sdk":"^1.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.0.0","jest":"^30.4.2","ts-jest":"^29.4.11","typescript":"^5.5.0","@types/jest":"^30.0.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/clover-mcp_1.0.3_1780815776988_0.3622818885799919","host":"s3://npm-registry-packages-npm-production"},"deprecated":"Package moved. See https://github.com/Ahreum-us/clover-mcp-server"},"1.0.4":{"name":"@dokdosolutions/clover-mcp","version":"1.0.4","_id":"@dokdosolutions/clover-mcp@1.0.4","maintainers":[{"name":"dokdosolutions","email":"dokdosolutions@gmail.com"}],"bin":{"clover-mcp":"dist/index.js"},"dist":{"shasum":"3b162928467570a727c53385faaef3e96fda3fa2","tarball":"https://registry.npmjs.org/@dokdosolutions/clover-mcp/-/clover-mcp-1.0.4.tgz","fileCount":19,"integrity":"sha512-qCAIEqu3fIzETyU6LNIA52/t4gZBAuEBBxpArITM2odDgbaz1c6CHWGcPJpNNBYmd+Cku+9eY6+Me5aQ+/E9mQ==","signatures":[{"sig":"MEUCICIx3ixcnfWX9ZCq/ybx/Bb0T7CvuEn1LkSdAvNcHX7XAiEAxUf7owrubMbJKVmNelitNRTAJ85R0Bsawm1UNRh6Qm0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":112801},"main":"dist/index.js","type":"module","engines":{"node":">=24"},"gitHead":"997e8276b325288252a7c3657759d5505acc01c6","mcpName":"io.github.dokdosolutions-us/lucky","scripts":{"dev":"tsx src/index.ts","test":"jest --config jest.config.cjs","build":"tsc","start":"node dist/index.js","inspector":"npx @modelcontextprotocol/inspector node dist/index.js","test:sandbox":"tsx scripts/run-tests.ts","prepublishOnly":"npm run build && npm test"},"_npmUser":{"name":"dokdosolutions","email":"dokdosolutions@gmail.com"},"_npmVersion":"10.9.7","description":"Model Context Protocol server for Clover POS — restaurant operations, menu management, inventory, analytics, and customer retention","directories":{},"_nodeVersion":"22.22.2","dependencies":{"zod":"^3.23.0","axios":"^1.7.0","bottleneck":"^2.19.5","axios-retry":"^4.5.0","@modelcontextprotocol/sdk":"^1.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.0.0","jest":"^30.4.2","ts-jest":"^29.4.11","typescript":"^5.5.0","@types/jest":"^30.0.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/clover-mcp_1.0.4_1780816744867_0.49370396090334356","host":"s3://npm-registry-packages-npm-production"},"deprecated":"Package moved. See https://github.com/Ahreum-us/clover-mcp-server"}},"time":{"created":"2026-06-06T03:56:18.068Z","modified":"2026-06-22T17:48:23.284Z","1.0.0":"2026-06-06T03:56:18.366Z","1.0.1":"2026-06-07T03:20:09.597Z","1.0.2":"2026-06-07T03:37:59.496Z","1.0.3":"2026-06-07T07:02:57.148Z","1.0.4":"2026-06-07T07:19:04.994Z"},"description":"Model Context Protocol server for Clover POS — restaurant operations, menu management, inventory, analytics, and customer retention","maintainers":[{"name":"dokdosolutions","email":"dokdosolutions@gmail.com"}],"readme":"# Lucky – Clover MCP Server 🍀✨\n\n**A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server for [🍀 Clover POS](https://www.clover.com) — giving AI agents direct access to restaurant operations: menu management, orders, inventory, analytics, customer retention, financial reporting, and more.**\n\nConnect any MCP-compatible AI (Claude, GPT-4, Cursor, Continue, and others) to your Clover merchant account and turn natural language into real POS actions — no dashboard, no manual lookups, no custom integration code.\n\nThis project was born out of a simple idea: restaurant owners — especially family-run, immigrant-owned restaurants — deserve the same kind of intelligent assistant that enterprise businesses take for granted. Not a chatbot. Not a dashboard. Something that watches your inventory, knows your regulars, and has your back during a dinner rush.\n\nWe built this as the data layer for an AI front-of-house system. It exposes the 🍀 Clover V3 REST API as a clean set of MCP tools that any LLM can call — so instead of logging into a dashboard to check stock levels or pull a sales report, you just ask.\n\nWe hope 🍀 Clover sees this and runs with it.\n\n---\n\n## What It Does\n\nThis server wraps the 🍀 Clover V3 API into **70+ LLM-callable tools** across every major area of restaurant operations:\n\n| Module | Tools |\n|---|---|\n| **Menu** | Browse items, categories, modifiers, and pricing |\n| **Orders** | Query orders, filter by date/status, inspect line items |\n| **Customers** | Search, create, and profile customers with lifetime spend |\n| **Inventory** | Stock levels, low-stock alerts, adjustments, auto-86 depleted items |\n| **Analytics** | Revenue by period, peak hours, best-selling items, category breakdown |\n| **Employees** | Shift activity, hours worked, clock-in/out visibility |\n| **Financials** | Daily/weekly/monthly summaries, tender breakdowns, tax reporting |\n| **Retention** | Lapsed customers, win-back message drafting, birthday outreach, first-time visitors |\n| **Operations** | Refund rates, open orders, void detection, table turn analysis |\n| **Forecasting** | Week-over-week trends, seasonal patterns, staffing demand signals |\n| **Reservations** | Booking management with conflict detection |\n| **Smart Queries** | Cross-module insights — happy hour analysis, upsell opportunities, slow day detection |\n| **Menu Ops** | Bulk pricing updates, happy hour scheduling, allergen tagging |\n\n---\n\n## Inspiration\n\nThe Model Context Protocol, open-sourced by Anthropic, makes it possible to give AI assistants structured, reliable access to external systems. We saw an opportunity to apply this to the restaurant industry — a space full of hardworking owners who are data-rich but time-poor.\n\nIndependent restaurants don't have engineering teams. They have POS data they never look at, regulars they forget to reach out to, and inventory that runs out at the worst possible time.\n\nA disproportionate number of independent restaurants in the US are owned by immigrant families — Vietnamese, Korean, Chinese, Mexican, Ethiopian, and countless others — where English may be a second language and the margin for error is razor-thin. These owners work harder than anyone, yet they're the last to benefit from technology that could actually lighten the load.\n\nThis project is built with them in mind. An AI that can answer customer questions in any language, surface the right data at the right time, and handle the operational noise — so the people who built something from nothing can focus on what they do best; provide and spend time with their family and loved ones.\n\nThis MCP server is the foundation for that.\n\n---\n\n## How This Differs From Other Clover MCP Servers\n\nThere are other MCP servers that wrap the 🍀 Clover API — and they're well built. But most of them are designed for **developers**: raw CRUD tools that expose every API endpoint so engineers can build on top of them.\n\nThis one is designed for **restaurant owners**.\n\nThe difference is in what the tools actually do. Instead of `clover_update_item_stock`, you get `adjust_inventory` — which validates your adjustment, guards against negative stock, and tells you what changed in plain language. Instead of a generic orders list, you get `get_lapsed_customers` — which surfaces your regulars who haven't been back in 30 days and drafts a win-back message for them.\n\nOther servers give an AI the ability to talk to 🍀 Clover. This one gives an AI the ability to help run a restaurant.\n\nThat's the Dokdo + 🍀 Clover difference.\n\n---\n\n## Getting Started\n\n### Prerequisites\n\n- Node.js 24+\n- A [🍀 Clover developer account](https://www.clover.com/developers) with an OAuth app\n- A 🍀 Clover merchant API token (sandbox or production)\n\n### Install via npm (recommended)\n\n```bash\nnpx @dokdosolutions/clover-mcp\n```\n\n### Or install from source\n\n```bash\nnpm install\nnpm run build\n```\n\n### Configure\n\n```bash\ncp .env.example .env\n# Fill in your CLOVER_ACCESS_TOKEN and CLOVER_MERCHANT_ID\n```\n\n### Run\n\n```bash\n# Production\nCLOVER_ACCESS_TOKEN=your_token CLOVER_MERCHANT_ID=your_merchant_id npm start\n\n# Sandbox (test against 🍀 Clover's sandbox environment)\nCLOVER_ACCESS_TOKEN=your_sandbox_token CLOVER_MERCHANT_ID=your_sandbox_merchant_id CLOVER_SANDBOX=true npm start\n```\n\n### Inspect Tools Interactively\n\n```bash\nCLOVER_ACCESS_TOKEN=your_token CLOVER_MERCHANT_ID=your_merchant_id CLOVER_SANDBOX=true npm run inspector\n```\n\nOpens the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) — a browser UI for calling tools and seeing live 🍀 Clover API responses.\n\n---\n\n## Multi-Store Setup\n\nEach 🍀 Clover location has its own merchant ID and API token. Run one instance per store:\n\n```json\n\"clover-store1\": {\n  \"command\": \"npx\",\n  \"args\": [\"-y\", \"@dokdosolutions/clover-mcp\"],\n  \"env\": {\n    \"CLOVER_ACCESS_TOKEN\": \"token_for_store1\",\n    \"CLOVER_MERCHANT_ID\": \"merchant_id_store1\"\n  }\n},\n\"clover-store2\": {\n  \"command\": \"npx\",\n  \"args\": [\"-y\", \"@dokdosolutions/clover-mcp\"],\n  \"env\": {\n    \"CLOVER_ACCESS_TOKEN\": \"token_for_store2\",\n    \"CLOVER_MERCHANT_ID\": \"merchant_id_store2\"\n  }\n}\n```\n\nEach instance gets its own rate limiter and retry budget — no cross-store interference.\n\n---\n\n## Testing\n\n```bash\n# Unit tests (no credentials needed)\nnpm test\n\n# Sandbox integration tests (requires 🍀 Clover sandbox credentials)\nCLOVER_ACCESS_TOKEN=your_token CLOVER_MERCHANT_ID=your_merchant_id CLOVER_SANDBOX=true npm run test:sandbox\n```\n\n---\n\n## Architecture\n\n- **`src/clover-client.ts`** — Axios-based HTTP client wrapping the 🍀 Clover V3 API, with rate limiting (Bottleneck), automatic retry with exponential backoff (axios-retry), and structured error handling\n- **`src/tools/`** — One file per domain, each exporting a `register*Tools` function\n- **`src/index.ts`** — Wires everything together into an MCP server over stdio\n\nRate limiting is per-instance (per 🍀 Clover merchant), so multi-store deployments stay isolated.\n\n---\n\n## Built By\n\n[Dokdo Solutions](https://github.com/dokdosolutions-us) — AI integration for independent restaurant owners.\n\n---\n\n## License\n\nMIT\n","readmeFilename":"README.md"}