Square MCP Server

Square Model Context Protocol Server (Beta)

Dieses Projekt folgt dem Model Context Protocol-Standard und ermöglicht KI-Assistenten die Interaktion mit der Connect-API von Square.

Schnellstart

Mit npx schnell und unkompliziert den Square MCP-Server starten:

# 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

Ersetzen Sie YOUR_SQUARE_ACCESS_TOKEN durch Ihr tatsächliches Square-Zugriffstoken. Ihr Zugriffstoken erhalten Sie, indem Sie der Anleitung unter Square Access Tokens folgen. Sie können auch Umgebungsvariablen setzen, bevor Sie den Befehl ausführen.

Remote-MCP-Server

Square bietet jetzt einen gehosteten Remote-MCP-Server an unter:

https://mcp.squareup.com/sse

Der Remote-MCP wird empfohlen, da er OAuth-Authentifizierung verwendet und Sie sich direkt mit Ihrem Square-Konto anmelden können, ohne Zugriffstoken manuell erstellen oder verwalten zu müssen.

Konfigurationsoptionen

Umgebungsvariable	Zweck	Beispiel
ACCESS_TOKEN	Ihr Square-API-Zugriffstoken	ACCESS_TOKEN=sq0atp-...
SANDBOX	Square-Sandbox-Umgebung verwenden	SANDBOX=true
PRODUCTION	Square-Produktivumgebung verwenden	PRODUCTION=true
DISALLOW_WRITES	Auf schreibgeschützte Operationen beschränken	DISALLOW_WRITES=true
SQUARE_VERSION	Square-API-Version angeben	SQUARE_VERSION=2025-04-16

Integration mit KI-Assistenten

Goose-Integration

So konfigurieren Sie den Square MCP-Server mit Goose:

Remote-MCP

Um den Square Remote-MCP in Goose zu installieren, klicken Sie auf einem Computer, auf dem Goose installiert ist, auf diese URL:

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

Oder kopieren Sie die URL und fügen Sie sie in die Adressleiste Ihres Browsers ein.

# Automatic installation
npx square-mcp-server install

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

Der Befehl install aktualisiert automatisch Ihre Goose-Konfiguration.

Claude Desktop-Integration

Informationen zur Claude Desktop-Integration finden Sie im Model Context Protocol Quickstart Guide. Fügen Sie diese Konfiguration zu Ihrer claude_desktop_config.json hinzu:

Remote-MCP

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

Dieser Ansatz ermöglicht es Ihnen, sich direkt mit Ihren Square-Kontoanmeldedaten zu authentifizieren, ohne Zugriffstoken verwalten zu müssen.

Lokaler MCP

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

Tool-Referenz

Der Square MCP-Server bietet einen optimierten Satz von Tools für die Interaktion mit Square-APIs:

Tool	Beschreibung	Hauptverwendung
get_service_info	Verfügbare Methoden für einen Dienst entdecken	Erkundung und Entdeckung
get_type_info	Detaillierte Parameteranforderungen abrufen	Anfragevorbereitung
make_api_request	API-Aufrufe an Square ausführen	Operationen durchführen

Dienstkatalog

Der Square MCP-Server bietet Zugriff auf das gesamte API-Ökosystem von Square. In der Square API-Dokumentation finden Sie detaillierte Informationen zu jedem Dienst:

Dienst	Beschreibung
applepay	Apple Pay-Integration
bankaccounts	Bankkontoverwaltung
bookingcustomattributes	Benutzerdefinierte Attribute für Buchungen
bookings	Terminbuchungsverwaltung
cards	Zahlungskartenverwaltung
cashdrawers	Bargeldschubladenverwaltung
catalog	Katalogverwaltung (Artikel, Kategorien usw.)
checkout	Checkout und Zahlungsabwicklung
customercustomattributes	Benutzerdefinierte Attribute für Kunden
customergroups	Kundengruppierung
customersegments	Kundensegmentierung
customers	Kundenverwaltung
devices	Square-Geräteverwaltung
disputes	Bearbeitung von Zahlungsstreitigkeiten
events	Ereignisverfolgung
giftcardactivities	Aktivitätsverfolgung für Geschenkkarten
giftcards	Geschenkkartenverwaltung
inventory	Bestandsverfolgung
invoices	Rechnungsverwaltung
labor	Personalverwaltung
locationcustomattributes	Benutzerdefinierte Attribute für Standorte
locations	Standortverwaltung
loyalty	Treueprogrammverwaltung
merchantcustomattributes	Benutzerdefinierte Attribute für Händler
merchants	Händlerkontoverwaltung
oauth	Authentifizierung
ordercustomattributes	Benutzerdefinierte Attribute für Bestellungen
orders	Bestellverwaltung
payments	Zahlungsabwicklung
payouts	Auszahlungsverwaltung
refunds	Rückerstattungsverwaltung
sites	Website-Integration
snippets	Square Online Code-Integration
subscriptions	Abonnementverwaltung
team	Mitarbeiterverwaltung
terminal	Square Terminal-Verwaltung
vendors	Lieferantenverwaltung
webhooksubscriptions	Ereignisbenachrichtigungen

Verwendungsmuster

Für eine optimale Interaktion mit der Square-API über MCP:

1. Entdecken: Verwenden Sie get_service_info, um verfügbare Methoden zu erkunden

   get_service_info(service: "catalog")
   

2. Verstehen: Verwenden Sie get_type_info, um die Parameteranforderungen kennenzulernen

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

3. Ausführen: Verwenden Sie make_api_request, um die Operation durchzuführen

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

Entwicklung und Debugging

Verwendung des MCP Inspector

Der MCP Inspector bietet eine visuelle Oberfläche zum Testen:

# Build the project
npm run build

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

Entwicklungsworkflow

1. Repository klonen
2. Abhängigkeiten installieren: npm install
3. Entwicklungsmodus starten: npm run watch
4. Server ausführen: node dist/index.js start
5. Änderungen mit dem MCP Inspector testen

Mitwirken

Dieses Repository wird automatisch aus der OpenAPI-Spezifikation von Square generiert. Beiträge sind willkommen, aber bitte beachten Sie, dass Änderungen in den Generator integriert werden müssen, der diesen Code erzeugt. Bitte eröffnen Sie ein Issue, um geplante Änderungen zu besprechen, bevor Sie einen Pull-Request einreichen.