Clover MCP (Model Context Protocol) 服务器

一个用于通过 OAuth 认证与 Clover API 交互的最小 MCP 服务器。

概述

此 MCP 服务器允许生成式 AI 模型和其他客户端使用 Model Context Protocol 访问您的 Clover 商家数据。通过这种集成，模型可以：

• 获取商家信息
• 列出库存项目
• 列出订单
• 访问单个项目和订单

快速开始

使用 Claude AI（推荐）

1. 将以下内容添加到您的 Claude MCP 设置中（通常在 ~/.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"]
    }
  }
}

1. 与 Claude 一起使用它：

/mcp use clover

1. 在与 Claude 的对话中启动 OAuth 流程：

Can you help me connect to my Clover account?

通过命令行使用

您可以直接运行 MCP 服务器：

# 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 设置

在使用此 MCP 服务器之前，您需要设置一个 Clover 应用程序：

1. 在 developer.clover.com 创建一个 Clover 开发者帐户
2. 在 Clover 开发者仪表板中注册一个新的应用程序
3. 配置您的应用：
   • 网站 URL: http://localhost:4000/oauth-callback
   • 默认 OAuth 响应: Code
4. 记录您的 Client ID 和 Client Secret
5. 将这些凭据添加到您的环境或 .env 文件中

MCP 工具

通过 MCP 协议可使用以下工具：

• get_oauth_status: 检查 OAuth 凭据是否可用
• initiate_oauth_flow: 启动 OAuth 流程以获取访问令牌
• get_merchant_info: 获取有关商家的信息
• list_inventory: 列出库存项目（可选过滤）
• list_orders: 列出订单（可选过滤）

与 Claude 示例使用

连接后，您可以使用以下示例提示与 Claude 交互：

1. 连接到 Clover:

   我想连接到我的 Clover 账户。
   

2. 获取商家信息:

   你有关于我的 Clover 商家账户的什么信息？
   

3. 列出库存项目:

   显示我库存中的前 10 项。
   

4. 列出订单:

   你能列出我最近的订单吗？
   

开发

本地安装

1. 克隆此仓库
2. 安装依赖项：

   npm install
   

3. 设置您的 OAuth 凭据：

   cp .env.example .env
   # 使用您的 Clover OAuth 凭据编辑 .env 文件
   

4. 构建 TypeScript 代码：

   npm run build
   

5. 启动 MCP 服务器：

   ./run.sh
   

发布更新

要将新版本发布到 npm：

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

# Build and publish
npm run build
npm publish

故障排除

如果您遇到 OAuth 问题：

1. 确认您的 Clover 应用已正确注册
2. 检查您的应用设置中的网站 URL 是否设置为 http://localhost:4000/oauth-callback
3. 确保您的 Client ID 和 Client Secret 是正确的
4. 确保开发人员仪表板中的“默认 OAuth 响应”设置为“Code”
5. 再次尝试使用 initiate_oauth_flow 启动 OAuth 流程

许可证

MIT