方形-MCP服务器

Name: 方形-MCP服务器
Author: square

作者：square89 星标更新：2025-07-22

安装使用来源：spider==github.com

项目介绍

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

该项目遵循模型上下文协议标准，允许AI助手与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`

与AI助手集成

Goose集成

要配置Square MCP服务器与Goose集成：

远程MCP

要在Goose中安装Square远程MCP，请点击以下URL，该链接应在已安装Goose的计算机上打开：

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 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终端管理
`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 提供了可视化的测试界面：

# 构建项目
npm run build

# 启动带有Square MCP服务器的Inspector
npx @modelcontextprotocol/inspector node dist/index.js start

开发工作流程

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

贡献

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