Square

oficial

Um servidor Model Context Protocol (MCP) para square

O que você pode fazer com Square MCP?

Descubra os métodos da API Square — Peça ao seu assistente para explorar as operações disponíveis para qualquer serviço Square, como catálogo ou pagamentos, usando get_service_info.
Entenda os parâmetros de solicitação — Faça seu assistente consultar os requisitos detalhados de parâmetros para um método específico da API antes de fazer uma chamada, via get_type_info.
Execute chamadas da API Square — Instrua seu assistente a realizar operações como listar inventário ou criar um pedido por meio de make_api_request.
Conecte-se ao Square MCP hospedado — Configure seu assistente de IA para autenticar com sua conta Square via OAuth usando o servidor remoto em https://mcp.squareup.com/mcp.

Servidor MCP hospedado

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

Instala no Claude Code, Codex, Cursor e outros

Documentação

Servidor Model Context Protocol da Square (Beta)

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

A maioria das pessoas deve usar o servidor hospedado. A Square executa um servidor MCP remoto em https://mcp.squareup.com/mcp com login OAuth; consulte a documentação do MCP da Square para configuração com seu assistente de IA. Este repositório é o servidor local e auto-hospedado: um ponto de partida se você quiser executar sua própria cópia. As alterações de código passam pelo gerador descrito em Contribuindo.

Square Model Context Protocol Server MCP server

Início Rápido

Comece a usar o servidor local com npx. Isso executa o servidor na sua própria máquina com seu próprio token de acesso; para o servidor hospedado, consulte a nota acima.

# 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 Tokens de Acesso da Square. Você também pode definir variáveis de ambiente antes de executar o comando.

Servidor MCP Remoto

A Square oferece um servidor MCP remoto hospedado em:

https://mcp.squareup.com/mcp

O servidor remoto é recomendado: ele usa OAuth, então você faz login com sua conta Square em vez de criar e gerenciar tokens de acesso. Guias de configuração para Claude, ChatGPT, Goose e outros assistentes estão na documentação do MCP da Square. O endpoint mais antigo https://mcp.squareup.com/sse ainda é servido para configurações SSE existentes.

Opções de Configuração

Variável de Ambiente	Finalidade	Exemplo
`ACCESS_TOKEN`	Seu token de acesso à API da 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 versão da API da Square	`SQUARE_VERSION=2025-04-16`

Integração com Assistentes de IA

Integração com Goose

Para configurar o Servidor MCP da Square com Goose:

MCP Remoto

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

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

Os comandos abaixo configuram o servidor local (npx square-mcp-server start), não o hospedado:

# 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 Guia de Início Rápido do Model Context Protocol. 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/mcp"]
    }
  }
}

Esta abordagem permite que você autentique diretamente com suas credenciais da 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 Servidor MCP da Square 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 solicitações
`make_api_request`	Executar chamadas de API para a Square	Realizar operações

Catálogo de Serviços

O Servidor MCP da Square fornece acesso ao ecossistema completo de APIs da Square. Consulte a Documentação da API da Square 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 programas de fidelidade
`merchantcustomattributes`	Atributos personalizados para comerciantes
`merchants`	Gerenciamento de contas de comerciante
`oauth`	Autenticação
`ordercustomattributes`	Atributos personalizados para pedidos
`orders`	Gerenciamento de pedidos
`payments`	Processamento de pagamentos
`payouts`	Gerenciamento de pagamentos
`refunds`	Gerenciamento de reembolsos
`sites`	Integração com sites
`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 interação ideal com a API da Square por meio do MCP:

Descubra: Use get_service_info para explorar métodos disponíveis
```
get_service_info(service: "catalog")
```
Entenda: Use get_type_info para aprender os requisitos de parâmetros
```
get_type_info(service: "catalog", method: "list")
```

Execute: 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 Desenvolvimento

Clone o repositório
Instale as dependências: npm install
Inicie o modo de desenvolvimento: npm run watch
Execute o servidor: node dist/index.js start
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. Abra uma issue para discutir as alterações propostas antes de enviar um pull request.