Square

官方

一个用于 Square 的模型上下文协议（MCP）服务器

你可以用 Square MCP 做什么？

发现 Square API 方法 — 让您的助手使用 get_service_info 探索任何 Square 服务（如目录或支付）的可用操作。
理解请求参数 — 在发起调用之前，让您的助手通过 get_type_info 查询特定 API 方法的详细参数要求。
执行 Square API 调用 — 指示您的助手通过 make_api_request 执行操作，例如列出库存或创建订单。
连接到托管的 Square MCP — 使用远程服务器 https://mcp.squareup.com/mcp，通过 OAuth 配置您的 AI 助手以对您的 Square 账户进行身份验证。

托管 MCP 服务器

npx add-mcp 'https://mcp.squareup.com/sse' --transport sse

可安装到 Claude Code、Codex、Cursor 等客户端

文档

Square 模型上下文协议服务器（测试版）

本项目遵循模型上下文协议标准，允许 AI 助手与 Square 的 connect API 进行交互。

大多数用户应使用托管服务器。 Square 在 https://mcp.squareup.com/mcp 运行远程 MCP 服务器，支持 OAuth 登录；有关与 AI 助手集成的设置，请参阅 Square MCP 文档。本仓库是本地自托管服务器：如果您想运行自己的副本，这是一个起点。代码更改通过“贡献”部分所述的生成器进行。

Square Model Context Protocol Server MCP server

快速开始

使用 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 集成，请参阅模型上下文协议快速入门指南。将此配置添加到您的 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 服务器提供对 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 进行最佳交互：

发现：使用 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 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

开发工作流程

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

贡献

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