Square Model Context Protocol Server (Beta)

Square Model Context Protocol 服务端（Beta）

该项目遵循 Model Context Protocol 标准，允许 AI 助手与 Square 的连接 API 交互。

大多数人应使用托管服务端。 Square 在 https://mcp.squareup.com/mcp 提供远程 MCP 服务，支持通过 OAuth 登录；有关如何为 AI 助手进行设置，请参阅 Square MCP 文档。此仓库是本地、可自托管的服务端：如果你想运行自己的副本，可从这里开始。代码变更通过「贡献」部分所述的生成器进行。

快速开始

使用 npx 快速启动本地服务端。此操作会在你自己的计算机上运行服务端，并使用你自己的访问令牌；有关托管服务端，请参阅上面的说明。

# Basic startup
npx square-mcp-server start

# With environment configuration
ACCESS_TOKEN=YOUR_SQUARE_ACCESS_TOKEN SANDBOX=true npx square-mcp-server start

# local runs
npx /path/to/project/square-mcp-server

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

远程 MCP 服务

Square 提供托管的远程 MCP 服务：

https://mcp.squareup.com/mcp

推荐使用远程服务：它采用 OAuth，因此你可以使用 Square 账户登录，而无需创建和管理访问令牌。有关 Claude、ChatGPT、Goose 和其他助手的设置指南，请参阅 Square MCP 文档。旧版 https://mcp.squareup.com/sse 端点仍在提供服务，以兼容现有的 SSE 配置。

配置选项

环境变量	用途	示例
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

与 AI 助手集成

Goose 集成

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

远程 MCP

要在 Goose 中安装 Square 远程 MCP，请在已安装 Goose 的计算机上点击此 URL：

goose://extension?cmd=npx&arg=mcp-remote&arg=https%3A%2F%2Fmcp.squareup.com%2Fmcp&id=square_mcp_production_remote&name=Square%20MCP%20Remote&description=Square%20Production%20MCP%20Remote

或者将 URL 复制并粘贴到浏览器地址栏中。

以下命令配置的是本地服务端（npx square-mcp-server start），而非托管服务端：

# Automatic installation
npx square-mcp-server install

# Get URL for manual installation
npx square-mcp-server get-goose-url

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

Claude Desktop 集成

有关 Claude Desktop 集成，请参阅 Model Context Protocol 快速入门指南。将此配置添加到你的 claude_desktop_config.json：

远程 MCP

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

此方法可让你直接使用 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 Server 可访问 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 Code 集成
subscriptions	订阅管理
team	员工管理
terminal	Square Terminal 管理
vendors	供应商管理
webhooksubscriptions	事件通知

使用模式

通过 MCP 与 Square API 交互时，为获得最佳效果，请按以下步骤操作：

1. 发现：使用 get_service_info 探索可用方法

   get_service_info(service: "catalog")
   

2. 了解：使用 get_type_info 了解参数要求

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

3. 执行：使用 make_api_request 执行操作

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

开发与调试

使用 MCP Inspector

MCP Inspector 提供了用于测试的可视化界面：

# Build the project
npm run build

# Start the inspector with the Square MCP Server
npx @modelcontextprotocol/inspector node dist/index.js start

开发工作流

1. 克隆代码库
2. 安装依赖项：npm install
3. 启动开发模式：npm run watch
4. 运行服务：node dist/index.js start
5. 使用 MCP Inspector 测试更改

贡献

此代码库由 Square 的 OpenAPI Specification 自动生成。欢迎贡献，但请注意，更改需要纳入生成此代码的生成器中。提交拉取请求前，请先创建 issue 讨论拟议的更改。