金大哥 - square-mcp MCP 详情

article

README

🚀 方形模型上下文协议服务器 (Beta)

本项目遵循模型上下文协议标准，允许人工智能助手与Square的连接API进行交互。

🚀 快速开始

使用npx启动并运行Square MCP服务器：

# 基本启动
npx square-mcp-server start

# 带有环境配置
ACCESS_TOKEN=YOUR_SQUARE_ACCESS_TOKEN SANDBOX=true npx square-mcp-server start

# 本地运行
npx /path/to/project/square-mcp-server

将 YOUR_SQUARE_ACCESS_TOKEN 替换为你实际的Square访问令牌。你可以按照 Square访问令牌中的指南获取访问令牌。你也可以在运行命令之前设置环境变量。

🌐 远程MCP服务器

Square现在在以下地址提供托管的远程MCP服务器：

https://mcp.squareup.com/sse

建议使用远程MCP，因为它使用OAuth认证，允许你直接使用Square账户登录，而无需手动创建或管理访问令牌。

⚙️ 配置选项

| 环境变量 | 用途 | 示例 | |---------------------|---------|---------| | ACCESS_TOKEN | 你的Square API访问令牌 | ACCESS_TOKEN=sq0atp-... | | SANDBOX | 使用Square沙盒环境 | SANDBOX=true | | PRODUCTION | 使用Square生产环境 | PRODUCTION=true | | DISALLOW_WRITES | 限制为只读操作 | DISALLOW_WRITES=true | | SQUARE_VERSION | 指定Square API版本 | SQUARE_VERSION=2025-04-16 |

🤖 与人工智能助手集成

Goose集成

要使用 Goose 配置Square MCP服务器：

远程MCP：要在Goose中安装Square远程MCP，请在安装了Goose的计算机上点击此URL： goose://extension?cmd=npx&arg=mcp-remote&arg=https%3A%2F%2Fmcp.squareup.com%2Fsse&id=square_mcp_production_remote&name=Square%20MCP%20Remote&description=Square%20Production%20MCP%20Remote 或者将URL复制并粘贴到你的浏览器地址栏中。

# 自动安装
npx square-mcp-server install

# 获取手动安装的URL
npx square-mcp-server get-goose-url

install 命令会自动更新你的Goose配置。

Claude桌面集成

对于Claude桌面集成，请参阅模型上下文协议快速入门指南。将以下配置添加到你的 claude_desktop_config.json 中：

远程MCP：

{
  "mcpServers": {
    "mcp_square_api": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp.squareup.com/sse"]
    }
  }
}

这种方法允许你直接使用Square账户凭证进行认证，而无需管理访问令牌。

本地MCP：

{
  "mcpServers": {
    "mcp_square_api": {
      "command": "npx",
      "args": ["square-mcp-server", "start"],
      "env": {
        "ACCESS_TOKEN": "YOUR_SQUARE_ACCESS_TOKEN",
        "SANDBOX": "true"
      }
    }
  }
}

🛠️ 工具参考

Square MCP服务器提供了一套简化的工具，用于与Square API进行交互： | 工具 | 描述 | 主要用途 | |------|-------------|------------| | get_service_info | 发现服务可用的方法 | 探索和发现 | | get_type_info | 获取详细的参数要求 | 请求准备 | | make_api_request | 执行对Square的API调用 | 执行操作 |

📚 服务目录

Square MCP服务器提供对Square完整 API生态系统的访问。有关每个服务的详细信息，请查看 Square API文档： | 服务 | 描述 | |---------|-------------| | applepay | Apple Pay集成 | | bankaccounts | 银行账户管理 | | bookingcustomattributes | 预订的自定义属性 | | bookings | 预约预订管理 | | cards | 支付卡管理 | | cashdrawers | 收银机管理 | | catalog | 目录管理（商品、类别等） | | checkout | 结账和支付处理 | | customercustomattributes | 客户的自定义属性 | | customergroups | 客户分组 | | customersegments | 客户细分 | | customers | 客户管理 | | devices | Square设备管理 | | disputes | 支付纠纷处理 | | events | 事件跟踪 | | giftcardactivities | 礼品卡活动跟踪 | | giftcards | 礼品卡管理 | | inventory | 库存跟踪 | | invoices | 发票管理 | | labor | 劳动力管理 | | locationcustomattributes | 地点的自定义属性 | | locations | 地点管理 | | loyalty | 忠诚度计划管理 | | merchantcustomattributes | 商家的自定义属性 | | merchants | 商家账户管理 | | oauth | 认证 | | ordercustomattributes | 订单的自定义属性 | | orders | 订单管理 | | payments | 支付处理 | | payouts | 支出管理 | | refunds | 退款管理 | | sites | 网站集成 | | snippets | Square Online代码集成 | | subscriptions | 订阅管理 | | team | 员工管理 | | terminal | Square终端管理 | | vendors | 供应商管理 | | webhooksubscriptions | 事件通知 |

📝 使用模式

为了通过MCP与Square API进行最佳交互：

发现：使用 get_service_info 探索可用的方法
```
get_service_info(service: "catalog")
```

理解：使用 get_type_info 了解参数要求

get_type_info(service: "catalog", method: "list")

执行：使用 make_api_request 执行操作

make_api_request(service: "catalog", method: "list", request: {})

🛠️ 开发与调试

使用MCP检查器

MCP检查器提供了一个可视化界面用于测试：

# 构建项目
npm run build

# 使用Square MCP服务器启动检查器
npx @modelcontextprotocol/inspector node dist/index.js start

开发工作流程

克隆仓库
安装依赖：npm install
启动开发模式：npm run watch
运行服务器：node dist/index.js start
使用MCP检查器测试你的更改

🤝 贡献

此仓库是从Square的OpenAPI规范自动生成的。虽然欢迎贡献，但请注意，更改需要合并到生成此代码的生成器中。请在提交拉取请求之前打开一个问题来讨论提议的更改。

square-mcp