Square

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

Square 模型上下文協定伺服器（Beta）

本專案遵循 模型上下文協定 標準，讓 AI 助手能夠與 Square 的 connect API 互動。

大多數使用者應使用託管伺服器。 Square 在 https://mcp.squareup.com/mcp 執行遠端 MCP 伺服器，並提供 OAuth 登入；請參閱 Square MCP 文件 以了解如何與您的 AI 助手進行設定。本儲存庫是本地端、自行託管的伺服器：如果您想執行自己的副本，這是一個起點。程式碼變更會透過「貢獻」一節所述的產生器進行。

快速開始

使用 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 進行最佳互動：

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 規格自動產生的。雖然歡迎貢獻，但請注意，變更需要納入產生此程式碼的產生器中。請在提交 pull request 之前開啟 issue 討論建議的變更。