Square

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

Square Model Context Protocol Server (Beta)

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

Die meisten Benutzer sollten den gehosteten Server verwenden. Square betreibt einen Remote-MCP-Server unter https://mcp.squareup.com/mcp mit OAuth-Anmeldung; siehe die Square MCP-Dokumentation für die Einrichtung mit Ihrem KI-Assistenten. Dieses Repository ist der lokale, selbst gehostete Server: ein Ausgangspunkt, wenn Sie Ihre eigene Kopie ausführen möchten. Codeänderungen durchlaufen den Generator, der unter „Contributing" beschrieben ist.

Schnellstart

Starten Sie den lokalen Server mit npx. Dies führt den Server auf Ihrem eigenen Rechner mit Ihrem eigenen Zugriffstoken aus; für den gehosteten Server siehe den Hinweis oben.

# 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. Sie erhalten Ihr Zugriffstoken, indem Sie der Anleitung unter Square Access Tokens folgen. Sie können auch Umgebungsvariablen festlegen, bevor Sie den Befehl ausführen.

Remote-MCP-Server

Square bietet einen gehosteten Remote-MCP-Server unter:

https://mcp.squareup.com/mcp

Der Remote-Server wird empfohlen: Er verwendet OAuth, sodass Sie sich mit Ihrem Square-Konto anmelden, anstatt Zugriffstokens zu erstellen und zu verwalten. Einrichtungsanleitungen für Claude, ChatGPT, Goose und andere Assistenten finden Sie in der Square MCP-Dokumentation. Der ältere https://mcp.squareup.com/sse-Endpunkt wird weiterhin für bestehende SSE-Konfigurationen bereitgestellt.

Konfigurationsoptionen

Umgebungsvariable	Zweck	Beispiel
ACCESS_TOKEN	Ihr Square-API-Zugriffstoken	ACCESS_TOKEN=sq0atp-...
SANDBOX	Square-Sandbox-Umgebung verwenden	SANDBOX=true
PRODUCTION	Square-Produktionsumgebung verwenden	PRODUCTION=true
DISALLOW_WRITES	Auf schreibgeschützte Vorgänge 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 das Square-Remote-MCP in Goose zu installieren, klicken Sie auf diese URL auf einem Computer, auf dem Goose installiert ist:

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

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

Die folgenden Befehle konfigurieren den lokalen Server (npx square-mcp-server start), nicht den gehosteten:

# Automatic installation
npx square-mcp-server install

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

Der install-Befehl aktualisiert automatisch Ihre Goose-Konfiguration.

Claude-Desktop-Integration

Für die Claude-Desktop-Integration siehe den 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/mcp"]
    }
  }
}

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

Lokales 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 eine optimierte Reihe von Tools für die Interaktion mit Square-APIs:

Tool	Beschreibung	Hauptverwendung
get_service_info	Verfügbare Methoden für einen Dienst ermitteln	Erkundung und Entdeckung
get_type_info	Detaillierte Parameteranforderungen abrufen	Anforderungsvorbereitung
make_api_request	API-Aufrufe an Square ausführen	Durchführung von Vorgängen

Servicekatalog

Der Square MCP Server bietet Zugriff auf das vollständige API-Ökosystem von Square. Weitere Informationen zu jedem Dienst finden Sie in der Square-API-Dokumentation:

Service	Beschreibung
applepay	Apple-Pay-Integration
bankaccounts	Bankkontoverwaltung
bookingcustomattributes	Benutzerdefinierte Attribute für Buchungen
bookings	Terminbuchungsverwaltung
cards	Zahlungskartenverwaltung
cashdrawers	Kassenladenverwaltung
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	Geschenkkarten-Aktivitätsverfolgung
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	Personalverwaltung
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 Parameteranforderungen zu erfahren

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

3. Ausführen: Verwenden Sie make_api_request, um den Vorgang durchzuführen

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

Entwicklung und Debugging

Verwendung des MCP Inspectors

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. Testen Sie Ihre Änderungen mit dem MCP Inspector

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 eingearbeitet werden müssen, der diesen Code erzeugt. Bitte eröffnen Sie ein Issue, um vorgeschlagene Änderungen zu besprechen, bevor Sie einen Pull-Request einreichen.