Square MCP Server

Square Model Context Protocol Server (Beta)

Este projeto segue o padrão Model Context Protocol, permitindo que assistentes de IA interajam com a API connect da Square.

Início Rápido

Comece a usar o servidor Square MCP com 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

Substitua YOUR_SQUARE_ACCESS_TOKEN pelo seu token de acesso real da Square. Você pode obter seu token de acesso seguindo o guia em Square Access Tokens. Você também pode definir variáveis de ambiente antes de executar o comando.

Servidor MCP Remoto

A Square agora oferece um servidor MCP remoto hospedado em:

https://mcp.squareup.com/sse

O MCP remoto é recomendado, pois usa autenticação OAuth, permitindo que você faça login diretamente com sua conta Square, sem precisar criar ou gerenciar tokens de acesso manualmente.

Opções de Configuração

Variável de Ambiente	Finalidade	Exemplo
ACCESS_TOKEN	Seu token de acesso da API Square	ACCESS_TOKEN=sq0atp-...
SANDBOX	Usar ambiente sandbox da Square	SANDBOX=true
PRODUCTION	Usar ambiente de produção da Square	PRODUCTION=true
DISALLOW_WRITES	Restringir a operações somente leitura	DISALLOW_WRITES=true
SQUARE_VERSION	Especificar a versão da API Square	SQUARE_VERSION=2025-04-16

Integração com Assistentes de IA

Integração com Goose

Para configurar o Square MCP Server com o Goose:

MCP Remoto

Para instalar o MCP remoto da Square no Goose, clique neste URL em um computador onde o 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

Ou copie e cole o URL na barra de endereços do seu navegador.

# Automatic installation
npx square-mcp-server install

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

O comando install atualiza automaticamente sua configuração do Goose.

Integração com Claude Desktop

Para integração com Claude Desktop, consulte o Model Context Protocol Quickstart Guide. Adicione esta configuração ao seu claude_desktop_config.json:

MCP Remoto

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

Esta abordagem permite que você autentique diretamente com as credenciais da sua conta Square, sem precisar gerenciar tokens de acesso.

MCP Local

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

Referência de Ferramentas

O Square MCP Server fornece um conjunto simplificado de ferramentas para interagir com as APIs da Square:

Ferramenta	Descrição	Uso Principal
get_service_info	Descobrir métodos disponíveis para um serviço	Exploração e descoberta
get_type_info	Obter requisitos detalhados de parâmetros	Preparação de requisições
make_api_request	Executar chamadas de API para a Square	Realizar operações

Catálogo de Serviços

O Square MCP Server fornece acesso ao ecossistema completo de APIs da Square. Confira a Square API Documentation para informações detalhadas sobre cada serviço:

Serviço	Descrição
applepay	Integração com Apple Pay
bankaccounts	Gerenciamento de contas bancárias
bookingcustomattributes	Atributos personalizados para reservas
bookings	Gerenciamento de agendamentos
cards	Gerenciamento de cartões de pagamento
cashdrawers	Gerenciamento de gaveta de dinheiro
catalog	Gerenciamento de catálogo (itens, categorias, etc.)
checkout	Checkout e processamento de pagamentos
customercustomattributes	Atributos personalizados para clientes
customergroups	Agrupamento de clientes
customersegments	Segmentação de clientes
customers	Gerenciamento de clientes
devices	Gerenciamento de dispositivos Square
disputes	Tratamento de disputas de pagamento
events	Rastreamento de eventos
giftcardactivities	Rastreamento de atividades de cartões-presente
giftcards	Gerenciamento de cartões-presente
inventory	Rastreamento de inventário
invoices	Gerenciamento de faturas
labor	Gerenciamento de força de trabalho
locationcustomattributes	Atributos personalizados para locais
locations	Gerenciamento de locais
loyalty	Gerenciamento de programa de fidelidade
merchantcustomattributes	Atributos personalizados para comerciantes
merchants	Gerenciamento de conta de comerciante
oauth	Autenticação
ordercustomattributes	Atributos personalizados para pedidos
orders	Gerenciamento de pedidos
payments	Processamento de pagamentos
payouts	Gerenciamento de pagamentos a receber
refunds	Gerenciamento de reembolsos
sites	Integração com website
snippets	Integração com Square Online Code
subscriptions	Gerenciamento de assinaturas
team	Gerenciamento de equipe
terminal	Gerenciamento do Square Terminal
vendors	Gerenciamento de fornecedores
webhooksubscriptions	Notificações de eventos

Padrão de Uso

Para uma interação ideal com a API Square através do MCP:

1. Descobrir: Use get_service_info para explorar os métodos disponíveis

   get_service_info(service: "catalog")
   

2. Entender: Use get_type_info para aprender os requisitos dos parâmetros

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

3. Executar: Use make_api_request para realizar a operação

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

Desenvolvimento e Depuração

Usando o MCP Inspector

O MCP Inspector fornece uma interface visual para testes:

# Build the project
npm run build

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

Fluxo de Trabalho de Desenvolvimento

1. Clone o repositório
2. Instale as dependências: npm install
3. Inicie o modo de desenvolvimento: npm run watch
4. Execute o servidor: node dist/index.js start
5. Teste suas alterações usando o MCP Inspector

Contribuindo

Este repositório é gerado automaticamente a partir da Especificação OpenAPI da Square. Embora contribuições sejam bem-vindas, observe que as alterações precisarão ser incorporadas ao gerador que produz este código. Por favor, abra uma issue para discutir as mudanças propostas antes de enviar um pull request.