Square

oficial

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

¿Qué puedes hacer con Square MCP?

Descubre los métodos de la API de Square — Pídele a tu asistente que explore las operaciones disponibles para cualquier servicio de Square, como catálogo o pagos, usando get_service_info.
Comprende los parámetros de las solicitudes — Haz que tu asistente consulte los requisitos detallados de parámetros para un método específico de la API antes de realizar una llamada, mediante get_type_info.
Ejecuta llamadas a la API de Square — Indica a tu asistente que realice operaciones como listar inventario o crear un pedido a través de make_api_request.
Conéctate al MCP alojado de Square — Configura tu asistente de IA para que se autentique con tu cuenta de Square mediante OAuth usando el servidor remoto en https://mcp.squareup.com/mcp.

Servidor MCP alojado

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

Se instala en Claude Code, Codex, Cursor y más

Documentación

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

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

La mayoría de las personas deberían usar el servidor alojado. Square ejecuta un servidor MCP remoto en https://mcp.squareup.com/mcp con inicio de sesión OAuth; consulta la documentación de MCP de Square para configurarlo con tu asistente de IA. Este repositorio es el servidor local autohospedado: un punto de partida si deseas ejecutar tu propia copia. Los cambios de código pasan por el generador descrito en Contribuciones.

Square Model Context Protocol Server MCP server

Inicio Rápido

Ponte en marcha con el servidor local usando npx. Esto ejecuta el servidor en tu propia máquina con tu propio token de acceso; para el servidor alojado, consulta la nota anterior.

# 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

Reemplaza YOUR_SQUARE_ACCESS_TOKEN con tu token de acceso real de Square. Puedes obtener tu token de acceso siguiendo la guía en Tokens de Acceso de Square. También puedes configurar variables de entorno antes de ejecutar el comando.

Servidor MCP Remoto

Square ofrece un servidor MCP remoto alojado en:

https://mcp.squareup.com/mcp

Se recomienda el servidor remoto: utiliza OAuth, por lo que inicias sesión con tu cuenta de Square en lugar de crear y gestionar tokens de acceso. Las guías de configuración para Claude, ChatGPT, Goose y otros asistentes están en la documentación de MCP de Square. El endpoint anterior https://mcp.squareup.com/sse todavía se sirve para configuraciones SSE existentes.

Opciones de Configuración

Variable de Entorno	Propósito	Ejemplo
`ACCESS_TOKEN`	Tu token de acceso a la API de Square	`ACCESS_TOKEN=sq0atp-...`
`SANDBOX`	Usar el entorno sandbox de Square	`SANDBOX=true`
`PRODUCTION`	Usar el entorno de producción de Square	`PRODUCTION=true`
`DISALLOW_WRITES`	Restringir a operaciones de solo lectura	`DISALLOW_WRITES=true`
`SQUARE_VERSION`	Especificar la 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, haz 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%2Fmcp&id=square_mcp_production_remote&name=Square%20MCP%20Remote&description=Square%20Production%20MCP%20Remote

O copia y pega la URL en la barra de direcciones de tu navegador.

Los comandos a continuación configuran el servidor local (npx square-mcp-server start), no el alojado:

# 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 tu configuración de Goose.

Integración con Claude Desktop

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

MCP Remoto

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

Este enfoque te permite autenticarte directamente con las credenciales de tu 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 APIs 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 a la API de Square	Realizar operaciones

Catálogo de Servicios

El Servidor MCP de Square proporciona acceso al ecosistema completo de APIs de Square. Consulta 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 cajones de efectivo
`catalog`	Gestión de catálogo (artículos, categorías, etc.)
`checkout`	Procesamiento de pagos y checkout
`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 pagos
`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
`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:

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

Ejecuta: Usa 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

Clona el repositorio
Instala las dependencias: npm install
Inicia el modo de desarrollo: npm run watch
Ejecuta el servidor: node dist/index.js start
Prueba tus cambios usando el Inspector MCP

Contribuciones

Este repositorio se genera automáticamente a partir de la Especificación OpenAPI de Square. Aunque las contribuciones son bienvenidas, ten en cuenta que los cambios deberán incorporarse al generador que produce este código. Abre un issue para discutir los cambios propuestos antes de enviar una solicitud de extracción.