Square MCP Server

Serveur Square Model Context Protocol (Bêta)

Ce projet suit la norme Model Context Protocol, permettant aux assistants IA d'interagir avec l'API connect de Square.

Démarrage rapide

Mettez en route le serveur Square MCP avec npx :

# 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

Remplacez YOUR_SQUARE_ACCESS_TOKEN par votre jeton d'accès Square réel. Vous pouvez obtenir votre jeton d'accès en suivant le guide Jetons d'accès Square. Vous pouvez également définir des variables d'environnement avant d'exécuter la commande.

Serveur MCP distant

Square propose désormais un serveur MCP distant hébergé à l'adresse :

https://mcp.squareup.com/sse

Le MCP distant est recommandé car il utilise l'authentification OAuth, vous permettant de vous connecter directement avec votre compte Square sans avoir à créer ou gérer manuellement des jetons d'accès.

Options de configuration

Variable d'environnement	Objectif	Exemple
ACCESS_TOKEN	Votre jeton d'accès à l'API Square	ACCESS_TOKEN=sq0atp-...
SANDBOX	Utiliser l'environnement bac à sable Square	SANDBOX=true
PRODUCTION	Utiliser l'environnement de production Square	PRODUCTION=true
DISALLOW_WRITES	Restreindre aux opérations en lecture seule	DISALLOW_WRITES=true
SQUARE_VERSION	Spécifier la version de l'API Square	SQUARE_VERSION=2025-04-16

Intégration avec les assistants IA

Intégration Goose

Pour configurer le serveur Square MCP avec Goose :

MCP distant

Pour installer le MCP distant Square dans Goose, cliquez sur cette URL sur un ordinateur où Goose est installé :

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

Ou copiez et collez l'URL dans la barre d'adresse de votre navigateur.

# Automatic installation
npx square-mcp-server install

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

La commande install met automatiquement à jour votre configuration Goose.

Intégration Claude Desktop

Pour l'intégration Claude Desktop, consultez le Guide de démarrage rapide Model Context Protocol. Ajoutez cette configuration à votre claude_desktop_config.json :

MCP distant

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

Cette approche vous permet de vous authentifier directement avec les identifiants de votre compte Square sans avoir à gérer de jetons d'accès.

MCP local

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

Référence des outils

Le serveur Square MCP fournit un ensemble simplifié d'outils pour interagir avec les API Square :

Outil	Description	Utilisation principale
get_service_info	Découvrir les méthodes disponibles pour un service	Exploration et découverte
get_type_info	Obtenir les exigences détaillées des paramètres	Préparation des requêtes
make_api_request	Exécuter des appels API vers Square	Réalisation d'opérations

Catalogue de services

Le serveur Square MCP donne accès à l'écosystème API complet de Square. Consultez la Documentation de l'API Square pour des informations détaillées sur chaque service :

Service	Description
applepay	Intégration Apple Pay
bankaccounts	Gestion des comptes bancaires
bookingcustomattributes	Attributs personnalisés pour les réservations
bookings	Gestion des rendez-vous
cards	Gestion des cartes de paiement
cashdrawers	Gestion des tiroirs-caisses
catalog	Gestion du catalogue (articles, catégories, etc.)
checkout	Paiement et traitement des transactions
customercustomattributes	Attributs personnalisés pour les clients
customergroups	Regroupement de clients
customersegments	Segmentation de la clientèle
customers	Gestion des clients
devices	Gestion des appareils Square
disputes	Traitement des litiges de paiement
events	Suivi des événements
giftcardactivities	Suivi de l'activité des cartes-cadeaux
giftcards	Gestion des cartes-cadeaux
inventory	Suivi des stocks
invoices	Gestion des factures
labor	Gestion des effectifs
locationcustomattributes	Attributs personnalisés pour les points de vente
locations	Gestion des points de vente
loyalty	Gestion du programme de fidélité
merchantcustomattributes	Attributs personnalisés pour les commerçants
merchants	Gestion du compte commerçant
oauth	Authentification
ordercustomattributes	Attributs personnalisés pour les commandes
orders	Gestion des commandes
payments	Traitement des paiements
payouts	Gestion des versements
refunds	Gestion des remboursements
sites	Intégration de site web
snippets	Intégration Square Online Code
subscriptions	Gestion des abonnements
team	Gestion du personnel
terminal	Gestion du Square Terminal
vendors	Gestion des fournisseurs
webhooksubscriptions	Notifications d'événements

Modèle d'utilisation

Pour une interaction optimale avec l'API Square via MCP :

1. Découvrir : Utilisez get_service_info pour explorer les méthodes disponibles

   get_service_info(service: "catalog")
   

2. Comprendre : Utilisez get_type_info pour connaître les exigences des paramètres

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

3. Exécuter : Utilisez make_api_request pour effectuer l'opération

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

Développement et débogage

Utilisation de MCP Inspector

Le MCP Inspector fournit une interface visuelle pour les tests :

# Build the project
npm run build

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

Flux de travail de développement

1. Cloner le dépôt
2. Installer les dépendances : npm install
3. Démarrer le mode développement : npm run watch
4. Exécuter le serveur : node dist/index.js start
5. Tester vos modifications à l'aide de MCP Inspector

Contribution

Ce dépôt est auto-généré à partir de la spécification OpenAPI de Square. Bien que les contributions soient les bienvenues, veuillez noter que les modifications devront être intégrées au générateur qui produit ce code. Veuillez ouvrir une issue pour discuter des modifications proposées avant de soumettre une pull request.