Square

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

Máy chủ Giao thức Ngữ cảnh Mô hình Square (Beta)

Dự án này tuân theo tiêu chuẩn Giao thức Ngữ cảnh Mô hình, cho phép các trợ lý AI tương tác với API connect của Square.

Hầu hết mọi người nên sử dụng máy chủ được lưu trữ. Square vận hành một máy chủ MCP từ xa tại https://mcp.squareup.com/mcp với tính năng đăng nhập OAuth; xem tài liệu MCP của Square để thiết lập với trợ lý AI của bạn. Kho lưu trữ này là máy chủ cục bộ, tự lưu trữ: một điểm khởi đầu nếu bạn muốn chạy bản sao của riêng mình. Các thay đổi mã được thực hiện thông qua trình tạo được mô tả trong phần Đóng góp.

Bắt đầu nhanh

Bắt đầu chạy máy chủ cục bộ bằng npx. Thao tác này chạy máy chủ trên máy của bạn với mã truy cập của riêng bạn; đối với máy chủ được lưu trữ, hãy xem ghi chú ở trên.

# 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

Thay YOUR_SQUARE_ACCESS_TOKEN bằng mã truy cập Square thực tế của bạn. Bạn có thể lấy mã truy cập của mình bằng cách làm theo hướng dẫn tại Mã truy cập Square. Bạn cũng có thể đặt các biến môi trường trước khi chạy lệnh.

Máy chủ MCP từ xa

Square cung cấp máy chủ MCP từ xa được lưu trữ tại:

https://mcp.squareup.com/mcp

Máy chủ từ xa được khuyến nghị: nó sử dụng OAuth, vì vậy bạn đăng nhập bằng tài khoản Square của mình thay vì tạo và quản lý mã truy cập. Hướng dẫn thiết lập cho Claude, ChatGPT, Goose và các trợ lý khác có trong tài liệu MCP của Square. Điểm cuối https://mcp.squareup.com/sse cũ hơn vẫn được phục vụ cho các cấu hình SSE hiện có.

Tùy chọn cấu hình

Biến môi trường	Mục đích	Ví dụ
ACCESS_TOKEN	Mã truy cập API Square của bạn	ACCESS_TOKEN=sq0atp-...
SANDBOX	Sử dụng môi trường sandbox của Square	SANDBOX=true
PRODUCTION	Sử dụng môi trường sản xuất của Square	PRODUCTION=true
DISALLOW_WRITES	Giới hạn chỉ các thao tác đọc	DISALLOW_WRITES=true
SQUARE_VERSION	Chỉ định phiên bản API Square	SQUARE_VERSION=2025-04-16

Tích hợp với trợ lý AI

Tích hợp Goose

Để cấu hình Máy chủ MCP Square với Goose:

MCP từ xa

Để cài đặt MCP từ xa của Square trong Goose, nhấp vào URL này trên máy tính đã cài Goose:

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

Hoặc sao chép và dán URL vào thanh địa chỉ trình duyệt của bạn.

Các lệnh bên dưới cấu hình máy chủ cục bộ (npx square-mcp-server start), không phải máy chủ được lưu trữ:

# Automatic installation
npx square-mcp-server install

# Get URL for manual installation
npx square-mcp-server get-goose-url

Lệnh install tự động cập nhật cấu hình Goose của bạn.

Tích hợp Claude Desktop

Để tích hợp Claude Desktop, hãy xem Hướng dẫn bắt đầu nhanh Giao thức Ngữ cảnh Mô hình. Thêm cấu hình này vào claude_desktop_config.json của bạn:

MCP từ xa

{
  "mcpServers": {
    "mcp_square_api": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp.squareup.com/mcp"]
    }
  }
}

Phương pháp này cho phép bạn xác thực trực tiếp bằng thông tin đăng nhập tài khoản Square của mình mà không cần quản lý mã truy cập.

MCP cục bộ

{
  "mcpServers": {
    "mcp_square_api": {
      "command": "npx",
      "args": ["square-mcp-server", "start"],
      "env": {
        "ACCESS_TOKEN": "YOUR_SQUARE_ACCESS_TOKEN",
        "SANDBOX": "true"
      }
    }
  }
}

Tham chiếu công cụ

Máy chủ MCP Square cung cấp một bộ công cụ hợp lý để tương tác với các API Square:

Công cụ	Mô tả	Sử dụng chính
get_service_info	Khám phá các phương thức có sẵn cho một dịch vụ	Khám phá và tìm hiểu
get_type_info	Lấy yêu cầu tham số chi tiết	Chuẩn bị yêu cầu
make_api_request	Thực hiện các lệnh gọi API đến Square	Thực hiện các thao tác

Danh mục dịch vụ

Máy chủ MCP Square cung cấp quyền truy cập vào hệ sinh thái API đầy đủ của Square. Xem Tài liệu API Square để biết thông tin chi tiết về từng dịch vụ:

Dịch vụ	Mô tả
applepay	Tích hợp Apple Pay
bankaccounts	Quản lý tài khoản ngân hàng
bookingcustomattributes	Thuộc tính tùy chỉnh cho đặt chỗ
bookings	Quản lý đặt lịch hẹn
cards	Quản lý thẻ thanh toán
cashdrawers	Quản lý ngăn kéo tiền mặt
catalog	Quản lý danh mục (sản phẩm, danh mục, v.v.)
checkout	Thanh toán và xử lý thanh toán
customercustomattributes	Thuộc tính tùy chỉnh cho khách hàng
customergroups	Nhóm khách hàng
customersegments	Phân khúc khách hàng
customers	Quản lý khách hàng
devices	Quản lý thiết bị Square
disputes	Xử lý tranh chấp thanh toán
events	Theo dõi sự kiện
giftcardactivities	Theo dõi hoạt động thẻ quà tặng
giftcards	Quản lý thẻ quà tặng
inventory	Theo dõi hàng tồn kho
invoices	Quản lý hóa đơn
labor	Quản lý lực lượng lao động
locationcustomattributes	Thuộc tính tùy chỉnh cho địa điểm
locations	Quản lý địa điểm
loyalty	Quản lý chương trình khách hàng thân thiết
merchantcustomattributes	Thuộc tính tùy chỉnh cho người bán
merchants	Quản lý tài khoản người bán
oauth	Xác thực
ordercustomattributes	Thuộc tính tùy chỉnh cho đơn hàng
orders	Quản lý đơn hàng
payments	Xử lý thanh toán
payouts	Quản lý thanh toán
refunds	Quản lý hoàn tiền
sites	Tích hợp trang web
snippets	Tích hợp mã Square Online
subscriptions	Quản lý đăng ký
team	Quản lý nhân viên
terminal	Quản lý Square Terminal
vendors	Quản lý nhà cung cấp
webhooksubscriptions	Thông báo sự kiện

Mẫu sử dụng

Để tương tác tối ưu với API Square thông qua MCP:

1. Khám phá: Sử dụng get_service_info để khám phá các phương thức có sẵn

   get_service_info(service: "catalog")
   

2. Hiểu: Sử dụng get_type_info để tìm hiểu các yêu cầu tham số

   get_type_info(service: "catalog", method: "list")
   

3. Thực hiện: Sử dụng make_api_request để thực hiện thao tác

   make_api_request(service: "catalog", method: "list", request: {})
   

Phát triển và gỡ lỗi

Sử dụng MCP Inspector

MCP Inspector cung cấp giao diện trực quan để kiểm tra:

# Build the project
npm run build

# Start the inspector with the Square MCP Server
npx @modelcontextprotocol/inspector node dist/index.js start

Quy trình phát triển

1. Sao chép kho lưu trữ
2. Cài đặt các phụ thuộc: npm install
3. Bắt đầu chế độ phát triển: npm run watch
4. Chạy máy chủ: node dist/index.js start
5. Kiểm tra các thay đổi của bạn bằng MCP Inspector

Đóng góp

Kho lưu trữ này được tự động tạo từ Đặc tả OpenAPI của Square. Mặc dù các đóng góp được hoan nghênh, xin lưu ý rằng các thay đổi sẽ cần được tích hợp vào trình tạo tạo ra mã này. Vui lòng mở một vấn đề để thảo luận về các thay đổi đề xuất trước khi gửi yêu cầu kéo.