Square

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

Square Model Context Protocol Sunucusu (Beta)

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

Çoğu kişi barındırılan sunucuyu kullanmalıdır. Square, https://mcp.squareup.com/mcp adresinde OAuth oturum açma ile uzak bir MCP sunucusu çalıştırır; yapay zeka asistanınızla kurulum için Square MCP dokümantasyonuna bakın. Bu depo, yerel, kendi kendine barındırılan sunucudur: kendi kopyanızı çalıştırmak istiyorsanız bir başlangıç noktasıdır. Kod değişiklikleri, Katkıda Bulunma bölümünde açıklanan üretici aracılığıyla yapılır.

Hızlı Başlangıç

npx kullanarak yerel sunucuyu çalıştırın. Bu, sunucuyu kendi makinenizde kendi erişim belirtecinizle çalıştırır; barındırılan sunucu için yukarıdaki nota bakı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 değerini gerçek Square erişim belirtecinizle değiştirin. Erişim belirtecinizi Square Erişim Belirteçleri kılavuzunu izleyerek alabilirsiniz. Komutu çalıştırmadan önce ortam değişkenlerini de ayarlayabilirsiniz.

Uzak MCP Sunucusu

Square, aşağıdaki adreste barındırılan bir uzak MCP sunucusu sunar:

https://mcp.squareup.com/mcp

Uzak sunucu önerilir: OAuth kullanır, böylece erişim belirteçleri oluşturup yönetmek yerine Square hesabınızla oturum açarsınız. Claude, ChatGPT, Goose ve diğer asistanlar için kurulum kılavuzları Square MCP dokümantasyonunda bulunmaktadır. Eski https://mcp.squareup.com/sse uç noktası, mevcut SSE yapılandırmaları için hâlâ sunulmaktadır.

Yapılandırma Seçenekleri

Ortam Değişkeni	Amaç	Örnek
ACCESS_TOKEN	Square API erişim belirteciniz	ACCESS_TOKEN=sq0atp-...
SANDBOX	Square sandbox 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ıyla Entegrasyon

Goose Entegrasyonu

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

Uzak MCP

Goose'a Square uzak MCP'sini kurmak için, Goose'un kurulu olduğu bir bilgisayarda bu URL'ye tıklayın:

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

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

Aşağıdaki komutlar yerel sunucuyu (npx square-mcp-server start) yapılandırır, barındırılanı değil:

# 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 Context Protocol Hızlı Başlangıç Kılavuzuna 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/mcp"]
    }
  }
}

Bu yaklaşım, erişim belirteçlerini yönetmenize gerek kalmadan doğrudan Square hesap bilgilerinizle kimlik doğrulamanı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'leriyle etkileşim için kapsamlı bir araç seti sağlar:

Araç	Açıklama	Birincil Kullanım
get_service_info	Bir hizmet için kullanılabilir yöntemleri keşfedin	Keşif ve inceleme
get_type_info	Ayrıntılı parametre gereksinimlerini alın	İstek hazırlama
make_api_request	Square'e API çağrıları yürütün	İş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ümantasyonuna göz atın:

Hizmet	Açıklama
applepay	Apple Pay entegrasyonu
bankaccounts	Banka hesabı yönetimi
bookingcustomattributes	Rezervasyonlar için özel nitelikler
bookings	Randevu rezervasyonu yönetimi
cards	Ödeme kartı yönetimi
cashdrawers	Kasa çekmecesi yönetimi
catalog	Katalog yönetimi (ürünler, kategoriler vb.)
checkout	Ödeme ve ödeme işleme
customercustomattributes	Müşteriler için özel nitelikler
customergroups	Müşteri gruplama
customersegments	Müşteri segmentasyonu
customers	Müşteri yönetimi
devices	Square cihaz yönetimi
disputes	Ödeme anlaşmazlığı işleme
events	Etkinlik 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	Satıcılar için özel nitelikler
merchants	Satıcı hesabı yönetimi
oauth	Kimlik doğrulama
ordercustomattributes	Siparişler için özel nitelikler
orders	Sipariş yönetimi
payments	Ödeme işleme
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	Etkinlik bildirimleri

Kullanım Deseni

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

1. Keşfedin: Kullanılabilir yöntemleri keşfetmek için get_service_info kullanın

   get_service_info(service: "catalog")
   

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

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

3. Yürütün: İş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şturulur. Katkılar memnuniyetle karşılanmakla birlikte, değişikliklerin bu kodu üreten üreticiye dahil edilmesi gerektiğini lütfen unutmayın. Bir çekme isteği göndermeden önce önerilen değişiklikleri tartışmak için lütfen bir sorun açın.