Square MCP Server

官方

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

GitHub

100

文档

Square 模型上下文协议服务器（Beta）

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

Square Model Context Protocol Server MCP server

快速开始

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

# 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/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`

与 AI 助手集成

Goose 集成

配置 Square MCP 服务器与 Goose 配合使用：

远程 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 复制并粘贴到浏览器的地址栏中。

# 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/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 在线代码集成
`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 规范自动生成的。欢迎贡献，但请注意，更改需要纳入生成此代码的生成器中。在提交拉取请求之前，请先打开一个问题来讨论拟议的更改。