Square MCP Server

oficial

Un servidor del Protocolo de Contexto de Modelo (MCP) para square

Documentación

Servidor del Protocolo de Contexto de Modelo de Square (Beta)

Este proyecto sigue el estándar Protocolo de Contexto de Modelo, permitiendo a los asistentes de IA interactuar con la API de conexión de Square.

Square Model Context Protocol Server MCP server

Inicio Rápido

Ponga en marcha el servidor MCP de Square usando 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

Reemplace YOUR_SQUARE_ACCESS_TOKEN con su token de acceso real de Square. Puede obtener su token de acceso siguiendo la guía en Tokens de Acceso de Square. También puede establecer variables de entorno antes de ejecutar el comando.

Servidor MCP Remoto

Square ahora ofrece un servidor MCP remoto alojado en:

https://mcp.squareup.com/sse

Se recomienda el MCP remoto ya que utiliza autenticación OAuth, permitiéndole iniciar sesión con su cuenta de Square directamente sin tener que crear o gestionar tokens de acceso manualmente.

Opciones de Configuración

Variable de Entorno	Propósito	Ejemplo
`ACCESS_TOKEN`	Su token de acceso a la API de Square	`ACCESS_TOKEN=sq0atp-...`
`SANDBOX`	Usar entorno sandbox de Square	`SANDBOX=true`
`PRODUCTION`	Usar entorno de producción de Square	`PRODUCTION=true`
`DISALLOW_WRITES`	Restringir a operaciones de solo lectura	`DISALLOW_WRITES=true`
`SQUARE_VERSION`	Especificar versión de la API de Square	`SQUARE_VERSION=2025-04-16`

Integración con Asistentes de IA

Integración con Goose

Para configurar el Servidor MCP de Square con Goose:

MCP Remoto

Para instalar el MCP remoto de Square en Goose, haga clic en esta URL en una computadora donde Goose esté instalado:

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

O copie y pegue la URL en la barra de direcciones de su navegador.

# Automatic installation
npx square-mcp-server install

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

El comando install actualiza automáticamente su configuración de Goose.

Integración con Claude Desktop

Para la integración con Claude Desktop, consulte la Guía de Inicio Rápido del Protocolo de Contexto de Modelo. Agregue esta configuración a su claude_desktop_config.json:

MCP Remoto

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

Este enfoque le permite autenticarse directamente con las credenciales de su cuenta de Square sin necesidad de gestionar tokens de acceso.

MCP Local

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

Referencia de Herramientas

El Servidor MCP de Square proporciona un conjunto simplificado de herramientas para interactuar con las API de Square:

Herramienta	Descripción	Uso Principal
`get_service_info`	Descubrir métodos disponibles para un servicio	Exploración y descubrimiento
`get_type_info`	Obtener requisitos detallados de parámetros	Preparación de solicitudes
`make_api_request`	Ejecutar llamadas API a Square	Realizar operaciones

Catálogo de Servicios

El Servidor MCP de Square proporciona acceso al ecosistema API completo de Square. Consulte la Documentación de la API de Square para obtener información detallada sobre cada servicio:

Servicio	Descripción
`applepay`	Integración con Apple Pay
`bankaccounts`	Gestión de cuentas bancarias
`bookingcustomattributes`	Atributos personalizados para reservas
`bookings`	Gestión de reservas de citas
`cards`	Gestión de tarjetas de pago
`cashdrawers`	Gestión de cajón de efectivo
`catalog`	Gestión de catálogo (artículos, categorías, etc.)
`checkout`	Procesamiento de pagos y caja
`customercustomattributes`	Atributos personalizados para clientes
`customergroups`	Agrupación de clientes
`customersegments`	Segmentación de clientes
`customers`	Gestión de clientes
`devices`	Gestión de dispositivos Square
`disputes`	Manejo de disputas de pago
`events`	Seguimiento de eventos
`giftcardactivities`	Seguimiento de actividad de tarjetas de regalo
`giftcards`	Gestión de tarjetas de regalo
`inventory`	Seguimiento de inventario
`invoices`	Gestión de facturas
`labor`	Gestión de fuerza laboral
`locationcustomattributes`	Atributos personalizados para ubicaciones
`locations`	Gestión de ubicaciones
`loyalty`	Gestión de programas de fidelización
`merchantcustomattributes`	Atributos personalizados para comerciantes
`merchants`	Gestión de cuentas de comerciante
`oauth`	Autenticación
`ordercustomattributes`	Atributos personalizados para pedidos
`orders`	Gestión de pedidos
`payments`	Procesamiento de pagos
`payouts`	Gestión de pagos a comerciantes
`refunds`	Gestión de reembolsos
`sites`	Integración con sitios web
`snippets`	Integración con Square Online Code
`subscriptions`	Gestión de suscripciones
`team`	Gestión de personal
`terminal`	Gestión de Square Terminal
`vendors`	Gestión de proveedores
`webhooksubscriptions`	Notificaciones de eventos

Patrón de Uso

Para una interacción óptima con la API de Square a través de MCP:

Descubrir: Use get_service_info para explorar los métodos disponibles
```
get_service_info(service: "catalog")
```
Entender: Use get_type_info para conocer los requisitos de los parámetros
```
get_type_info(service: "catalog", method: "list")
```

Ejecutar: Use make_api_request para realizar la operación

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

Desarrollo y Depuración

Uso del Inspector MCP

El Inspector MCP proporciona una interfaz visual para pruebas:

# Build the project
npm run build

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

Flujo de Trabajo de Desarrollo

Clonar el repositorio
Instalar dependencias: npm install
Iniciar modo de desarrollo: npm run watch
Ejecutar el servidor: node dist/index.js start
Probar sus cambios usando el Inspector MCP

Contribuciones

Este repositorio se genera automáticamente a partir de la Especificación OpenAPI de Square. Si bien las contribuciones son bienvenidas, tenga en cuenta que los cambios deberán incorporarse al generador que produce este código. Por favor, abra un issue para discutir los cambios propuestos antes de enviar un pull request.