Square MCP Server

chính thức

Một máy chủ Giao thức Ngữ cảnh Mô hình (MCP) dành cho square

GitHub

100

Tài liệu

Square Model Context Protocol Server (Beta)

Dự án này tuân theo tiêu chuẩn Model Context Protocol, cho phép các trợ lý AI tương tác với API kết nối của Square.

Square Model Context Protocol Server MCP server

Bắt Đầu Nhanh

Thiết lập và chạy máy chủ Square MCP bằng 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

Thay thế 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 bằng cách làm theo hướng dẫn tại Square Access Tokens. Bạn cũng có thể đặt biến môi trường trước khi chạy lệnh.

Máy Chủ MCP Từ Xa

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

https://mcp.squareup.com/sse

Máy chủ MCP từ xa được khuyến nghị vì nó sử dụng xác thực OAuth, cho phép bạn đăng nhập trực tiếp bằng tài khoản Square mà không cần tạo hoặc quản lý mã truy cập thủ công.

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 production của Square	`PRODUCTION=true`
`DISALLOW_WRITES`	Giới hạn chỉ 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ủ Square MCP với Goose:

MCP Từ Xa

Để cài đặt Square MCP từ xa trong Goose, nhấp vào URL này trên máy tính đã cài đặt 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

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

# 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, xem Model Context Protocol Quickstart Guide. 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/sse"]
    }
  }
}

Cách tiếp cận này cho phép bạn xác thực trực tiếp bằng thông tin tài khoản Square 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ủ Square MCP cung cấp một bộ công cụ tinh gọn để tương tác với các API của Square:

Công Cụ	Mô Tả	Mục Đích 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`	Nhận yêu cầu tham số chi tiết	Chuẩn bị yêu cầu
`make_api_request`	Thực thi lệnh gọi API đến Square	Thực hiện thao tác

Danh Mục Dịch Vụ

Máy Chủ Square MCP cung cấp quyền truy cập vào hệ sinh thái API hoàn chỉnh của Square. Xem Square API Documentation để 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 (mặt hàng, 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ý chi trả
`refunds`	Quản lý hoàn tiền
`sites`	Tích hợp trang web
`snippets`	Tích hợp Square Online Code
`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 Square API thông qua MCP:

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")
```
Hiểu rõ: Sử dụng get_type_info để tìm hiểu yêu cầu tham số
```
get_type_info(service: "catalog", method: "list")
```
Thực thi: 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 thử:

# 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

Sao chép kho lưu trữ
Cài đặt phụ thuộc: npm install
Bắt đầu chế độ phát triển: npm run watch
Chạy máy chủ: node dist/index.js start
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ạo tự động từ Đặc Tả OpenAPI của Square. Mặc dù các đóng góp đều đượ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 mã nguồn tạo ra mã này. Vui lòng mở một vấn đề để thảo luận về các thay đổi được đề xuất trước khi gửi yêu cầu kéo.