Square MCP Server

Square Model Bağlam Protokolü Sunucusu (Beta)

Bu proje, Model Bağlam Protokolü standardını takip ederek yapay zeka asistanlarının Square'in connect API'si ile etkileşime girmesini sağlar.

Hızlı Başlangıç

npx kullanarak Square MCP sunucusunu çalıştırmaya başlayı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

YOUR_SQUARE_ACCESS_TOKEN kısmını gerçek Square erişim anahtarınızla değiştirin. Erişim anahtarınızı Square Erişim Anahtarları rehberini takip ederek edinebilirsiniz. Ayrıca komutu çalıştırmadan önce ortam değişkenlerini de ayarlayabilirsiniz.

Uzak MCP Sunucusu

Square artık şu adreste barındırılan bir uzak MCP sunucusu sunmaktadır:

https://mcp.squareup.com/sse

Uzak MCP, OAuth kimlik doğrulaması kullandığı için önerilir; bu sayede erişim anahtarlarını manuel olarak oluşturmak veya yönetmek zorunda kalmadan doğrudan Square hesabınızla oturum açabilirsiniz.

Yapılandırma Seçenekleri

Ortam Değişkeni	Amacı	Örnek
ACCESS_TOKEN	Square API erişim anahtarınız	ACCESS_TOKEN=sq0atp-...
SANDBOX	Square korumalı alan ortamını kullan	SANDBOX=true
PRODUCTION	Square üretim ortamını kullan	PRODUCTION=true
DISALLOW_WRITES	Yalnızca salt okunur işlemlerle sınırla	DISALLOW_WRITES=true
SQUARE_VERSION	Square API sürümünü belirt	SQUARE_VERSION=2025-04-16

Yapay Zeka Asistanları ile Entegrasyon

Goose Entegrasyonu

Square MCP Sunucusunu Goose ile yapılandırmak için:

Uzak MCP

Square uzak MCP'yi Goose'a yüklemek için, Goose'un yüklü olduğu bir bilgisayarda bu URL'ye tıklayın:

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

Veya URL'yi tarayıcınızın adres çubuğuna kopyalayıp yapıştırın.

# Automatic installation
npx square-mcp-server install

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

install komutu, Goose yapılandırmanızı otomatik olarak günceller.

Claude Desktop Entegrasyonu

Claude Desktop entegrasyonu için Model Bağlam Protokolü Hızlı Başlangıç Rehberi'ne bakın. Bu yapılandırmayı claude_desktop_config.json dosyanıza ekleyin:

Uzak MCP

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

Bu yaklaşım, erişim anahtarlarını yönetmeye gerek kalmadan doğrudan Square hesap bilgilerinizle kimlik doğrulaması yapmanızı sağlar.

Yerel MCP

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

Araç Referansı

Square MCP Sunucusu, Square API'leri ile etkileşim için akıcı bir araç seti sunar:

Araç	Açıklama	Birincil Kullanım
get_service_info	Bir hizmet için mevcut yöntemleri keşfet	Keşif ve araştırma
get_type_info	Ayrıntılı parametre gereksinimlerini al	İstek hazırlığı
make_api_request	Square'e API çağrıları yürüt	İşlemleri gerçekleştirme

Hizmet Kataloğu

Square MCP Sunucusu, Square'in eksiksiz API ekosistemine erişim sağlar. Her hizmet hakkında ayrıntılı bilgi için Square API Dokümantasyonu'na göz atın:

Hizmet	Açıklama
applepay	Apple Pay entegrasyonu
bankaccounts	Banka hesabı yönetimi
bookingcustomattributes	Rezervasyonlar için özel nitelikler
bookings	Randevu rezervasyon yönetimi
cards	Ödeme kartı yönetimi
cashdrawers	Kasa çekmecesi yönetimi
catalog	Katalog yönetimi (ürünler, kategoriler vb.)
checkout	Ödeme ve işlem süreci
customercustomattributes	Müşteriler için özel nitelikler
customergroups	Müşteri gruplandırma
customersegments	Müşteri segmentasyonu
customers	Müşteri yönetimi
devices	Square cihaz yönetimi
disputes	Ödeme anlaşmazlığı işlemleri
events	Olay takibi
giftcardactivities	Hediye kartı etkinlik takibi
giftcards	Hediye kartı yönetimi
inventory	Envanter takibi
invoices	Fatura yönetimi
labor	İş gücü yönetimi
locationcustomattributes	Konumlar için özel nitelikler
locations	Konum yönetimi
loyalty	Sadakat programı yönetimi
merchantcustomattributes	İşletmeler için özel nitelikler
merchants	İşletme hesabı yönetimi
oauth	Kimlik doğrulama
ordercustomattributes	Siparişler için özel nitelikler
orders	Sipariş yönetimi
payments	Ödeme işlemleri
payouts	Ödeme yönetimi
refunds	İade yönetimi
sites	Web sitesi entegrasyonu
snippets	Square Online Code entegrasyonu
subscriptions	Abonelik yönetimi
team	Personel yönetimi
terminal	Square Terminal yönetimi
vendors	Tedarikçi yönetimi
webhooksubscriptions	Olay bildirimleri

Kullanım Deseni

MCP aracılığıyla Square API ile en iyi etkileşim için:

1. Keşfet: Mevcut yöntemleri keşfetmek için get_service_info kullanın

   get_service_info(service: "catalog")
   

2. Anla: Parametre gereksinimlerini öğrenmek için get_type_info kullanın

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

3. Yürüt: İşlemi gerçekleştirmek için make_api_request kullanın

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

Geliştirme ve Hata Ayıklama

MCP Inspector Kullanımı

MCP Inspector, test için görsel bir arayüz sağlar:

# Build the project
npm run build

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

Geliştirme İş Akışı

1. Depoyu klonlayın
2. Bağımlılıkları yükleyin: npm install
3. Geliştirme modunu başlatın: npm run watch
4. Sunucuyu çalıştırın: node dist/index.js start
5. Değişikliklerinizi MCP Inspector kullanarak test edin

Katkıda Bulunma

Bu depo, Square'in OpenAPI Spesifikasyonundan otomatik olarak oluşturulmuştur. Katkılar memnuniyetle karşılanır, ancak değişikliklerin bu kodu üreten oluşturucuya dahil edilmesi gerekeceğini lütfen unutmayın. Bir çekme isteği göndermeden önce önerilen değişiklikleri tartışmak için lütfen bir konu açın.