Square MCP Server

官方

一個用於 Square 的模型上下文協定（MCP）伺服器

GitHub

100

文件

Square 模型上下文協定伺服器 (Beta)

此專案遵循 Model Context Protocol 標準，允許 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 Access Tokens 的指南取得存取權杖。您也可以在執行指令前設定環境變數。

遠端 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 的電腦上點擊此網址：

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

或將網址複製並貼到瀏覽器的網址列。

# 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 Quickstart Guide。將此設定新增至您的 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 ecosystem 的存取。請參閱 Square API Documentation 以取得每個服務的詳細資訊：

服務	說明
`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 規範自動產生的。雖然歡迎貢獻，但請注意，變更需要整合到產生此程式碼的產生器中。在提交拉取請求之前，請先開啟一個議題來討論擬議的變更。