Square

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

Server Model Context Protocol Square (Beta)

Proyek ini mengikuti standar Model Context Protocol, yang memungkinkan asisten AI untuk berinteraksi dengan API connect Square.

Sebagian besar pengguna sebaiknya menggunakan server yang di-hosting. Square menjalankan server MCP jarak jauh di https://mcp.squareup.com/mcp dengan masuk melalui OAuth; lihat dokumentasi MCP Square untuk pengaturan dengan asisten AI Anda. Repositori ini adalah server lokal yang di-hosting sendiri: titik awal jika Anda ingin menjalankan salinan Anda sendiri. Perubahan kode melalui generator yang dijelaskan di bagian Berkontribusi.

Mulai Cepat

Jalankan server lokal menggunakan npx. Ini menjalankan server di mesin Anda sendiri dengan token akses Anda sendiri; untuk server yang di-hosting, lihat catatan di atas.

# 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

Ganti YOUR_SQUARE_ACCESS_TOKEN dengan token akses Square Anda yang sebenarnya. Anda dapat memperoleh token akses dengan mengikuti panduan di Token Akses Square. Anda juga dapat mengatur variabel lingkungan sebelum menjalankan perintah.

Server MCP Jarak Jauh

Square menawarkan server MCP jarak jauh yang di-hosting di:

https://mcp.squareup.com/mcp

Server jarak jauh direkomendasikan: server ini menggunakan OAuth, sehingga Anda masuk dengan akun Square alih-alih membuat dan mengelola token akses. Panduan pengaturan untuk Claude, ChatGPT, Goose, dan asisten lainnya tersedia di dokumentasi MCP Square. Endpoint https://mcp.squareup.com/sse yang lebih lama masih dilayani untuk konfigurasi SSE yang ada.

Opsi Konfigurasi

Variabel Lingkungan	Tujuan	Contoh
ACCESS_TOKEN	Token akses API Square Anda	ACCESS_TOKEN=sq0atp-...
SANDBOX	Gunakan lingkungan sandbox Square	SANDBOX=true
PRODUCTION	Gunakan lingkungan produksi Square	PRODUCTION=true
DISALLOW_WRITES	Batasi hanya operasi baca	DISALLOW_WRITES=true
SQUARE_VERSION	Tentukan versi API Square	SQUARE_VERSION=2025-04-16

Integrasi dengan Asisten AI

Integrasi Goose

Untuk mengonfigurasi Server MCP Square dengan Goose:

MCP Jarak Jauh

Untuk menginstal MCP jarak jauh Square di Goose, klik URL ini di komputer tempat Goose terinstal:

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

Atau salin dan tempel URL ke bilah alamat browser Anda.

Perintah di bawah ini mengonfigurasi server lokal (npx square-mcp-server start), bukan yang di-hosting:

# Automatic installation
npx square-mcp-server install

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

Perintah install secara otomatis memperbarui konfigurasi Goose Anda.

Integrasi Claude Desktop

Untuk integrasi Claude Desktop, lihat Panduan Mulai Cepat Model Context Protocol. Tambahkan konfigurasi ini ke claude_desktop_config.json Anda:

MCP Jarak Jauh

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

Pendekatan ini memungkinkan Anda untuk mengautentikasi langsung dengan kredensial akun Square tanpa perlu mengelola token akses.

MCP Lokal

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

Referensi Alat

Server MCP Square menyediakan serangkaian alat yang efisien untuk berinteraksi dengan API Square:

Alat	Deskripsi	Penggunaan Utama
get_service_info	Menemukan metode yang tersedia untuk layanan	Eksplorasi dan penemuan
get_type_info	Mendapatkan persyaratan parameter secara terperinci	Persiapan permintaan
make_api_request	Menjalankan panggilan API ke Square	Melakukan operasi

Katalog Layanan

Server MCP Square menyediakan akses ke ekosistem API Square yang lengkap. Lihat Dokumentasi API Square untuk informasi terperinci tentang setiap layanan:

Layanan	Deskripsi
applepay	Integrasi Apple Pay
bankaccounts	Manajemen rekening bank
bookingcustomattributes	Atribut kustom untuk pemesanan
bookings	Manajemen pemesanan janji temu
cards	Manajemen kartu pembayaran
cashdrawers	Manajemen laci kas
catalog	Manajemen katalog (item, kategori, dll.)
checkout	Pemrosesan checkout dan pembayaran
customercustomattributes	Atribut kustom untuk pelanggan
customergroups	Pengelompokan pelanggan
customersegments	Segmentasi pelanggan
customers	Manajemen pelanggan
devices	Manajemen perangkat Square
disputes	Penanganan sengketa pembayaran
events	Pelacakan acara
giftcardactivities	Pelacakan aktivitas kartu hadiah
giftcards	Manajemen kartu hadiah
inventory	Pelacakan inventaris
invoices	Manajemen faktur
labor	Manajemen tenaga kerja
locationcustomattributes	Atribut kustom untuk lokasi
locations	Manajemen lokasi
loyalty	Manajemen program loyalitas
merchantcustomattributes	Atribut kustom untuk pedagang
merchants	Manajemen akun pedagang
oauth	Autentikasi
ordercustomattributes	Atribut kustom untuk pesanan
orders	Manajemen pesanan
payments	Pemrosesan pembayaran
payouts	Manajemen pembayaran keluar
refunds	Manajemen pengembalian dana
sites	Integrasi situs web
snippets	Integrasi Kode Online Square
subscriptions	Manajemen langganan
team	Manajemen staf
terminal	Manajemen Square Terminal
vendors	Manajemen pemasok
webhooksubscriptions	Notifikasi acara

Pola Penggunaan

Untuk interaksi optimal dengan API Square melalui MCP:

1. Temukan: Gunakan get_service_info untuk menjelajahi metode yang tersedia

   get_service_info(service: "catalog")
   

2. Pahami: Gunakan get_type_info untuk mempelajari persyaratan parameter

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

3. Jalankan: Gunakan make_api_request untuk melakukan operasi

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

Pengembangan dan Debugging

Menggunakan MCP Inspector

MCP Inspector menyediakan antarmuka visual untuk pengujian:

# Build the project
npm run build

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

Alur Kerja Pengembangan

1. Klon repositori
2. Instal dependensi: npm install
3. Mulai mode pengembangan: npm run watch
4. Jalankan server: node dist/index.js start
5. Uji perubahan Anda menggunakan MCP Inspector

Berkontribusi

Repositori ini dibuat secara otomatis dari Spesifikasi OpenAPI Square. Meskipun kontribusi diterima, perlu diketahui bahwa perubahan perlu dimasukkan ke dalam generator yang menghasilkan kode ini. Silakan buka masalah untuk mendiskusikan perubahan yang diusulkan sebelum mengirimkan permintaan tarik.