Square

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

Square Model Context Protocol Server (бета-версия)

Этот проект соответствует стандарту Model Context Protocol, что позволяет AI-ассистентам взаимодействовать с API Square Connect.

Большинству пользователей следует использовать размещённый сервер. Square запускает удалённый MCP-сервер на https://mcp.squareup.com/mcp с входом через OAuth; см. документацию Square MCP для настройки с вашим AI-ассистентом. Этот репозиторий — локальный, самостоятельно размещённый сервер: отправная точка, если вы хотите запустить собственную копию. Изменения кода проходят через генератор, описанный в разделе Contributing.

Быстрый старт

Запустите локальный сервер с помощью 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

Замените YOUR_SQUARE_ACCESS_TOKEN на ваш фактический токен доступа Square. Вы можете получить токен доступа, следуя руководству Square Access Tokens. Вы также можете задать переменные окружения перед запуском команды.

Удалённый MCP-сервер

Square предлагает размещённый удалённый MCP-сервер по адресу:

https://mcp.squareup.com/mcp

Рекомендуется использовать удалённый сервер: он использует OAuth, поэтому вы входите с помощью учётной записи Square вместо создания и управления токенами доступа. Руководства по настройке для Claude, ChatGPT, Goose и других ассистентов находятся в документации Square MCP. Более старая конечная точка https://mcp.squareup.com/sse по-прежнему обслуживается для существующих конфигураций SSE.

Варианты конфигурации

Переменная окружения	Назначение	Пример
ACCESS_TOKEN	Ваш токен доступа к API Square	ACCESS_TOKEN=sq0atp-...
SANDBOX	Использовать песочницу Square	SANDBOX=true
PRODUCTION	Использовать производственную среду Square	PRODUCTION=true
DISALLOW_WRITES	Ограничить операции только чтением	DISALLOW_WRITES=true
SQUARE_VERSION	Указать версию API Square	SQUARE_VERSION=2025-04-16

Интеграция с AI-ассистентами

Интеграция с Goose

Чтобы настроить Square MCP Server с Goose:

Удалённый MCP

Чтобы установить удалённый Square MCP в Goose, нажмите этот URL на компьютере, где установлен Goose:

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

Или скопируйте и вставьте URL в адресную строку браузера.

Приведённые ниже команды настраивают локальный сервер (npx square-mcp-server start), а не размещённый:

# Automatic installation
npx square-mcp-server install

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

Команда install автоматически обновляет вашу конфигурацию Goose.

Интеграция с Claude Desktop

Для интеграции с Claude Desktop см. Краткое руководство по Model Context Protocol. Добавьте эту конфигурацию в ваш claude_desktop_config.json:

Удалённый MCP

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

Этот подход позволяет аутентифицироваться напрямую с помощью учётных данных вашей учётной записи Square без необходимости управлять токенами доступа.

Локальный MCP

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

Справочник по инструментам

Square MCP Server предоставляет оптимизированный набор инструментов для взаимодействия с API Square:

Инструмент	Описание	Основное использование
get_service_info	Обнаружение методов, доступных для сервиса	Исследование и обнаружение
get_type_info	Получение подробных требований к параметрам	Подготовка запросов
make_api_request	Выполнение вызовов API к Square	Выполнение операций

Каталог сервисов

Square MCP Server предоставляет доступ к полной экосистеме API Square. Ознакомьтесь с документацией API Square для получения подробной информации о каждом сервисе:

Сервис	Описание
applepay	Интеграция Apple Pay
bankaccounts	Управление банковскими счетами
bookingcustomattributes	Пользовательские атрибуты для бронирований
bookings	Управление записью на приём
cards	Управление платёжными картами
cashdrawers	Управление денежным ящиком
catalog	Управление каталогом (товары, категории и т. д.)
checkout	Оформление заказа и обработка платежей
customercustomattributes	Пользовательские атрибуты для клиентов
customergroups	Группировка клиентов
customersegments	Сегментация клиентов
customers	Управление клиентами
devices	Управление устройствами Square
disputes	Обработка споров по платежам
events	Отслеживание событий
giftcardactivities	Отслеживание активности подарочных карт
giftcards	Управление подарочными картами
inventory	Отслеживание запасов
invoices	Управление счетами
labor	Управление персоналом
locationcustomattributes	Пользовательские атрибуты для местоположений
locations	Управление местоположениями
loyalty	Управление программой лояльности
merchantcustomattributes	Пользовательские атрибуты для продавцов
merchants	Управление учётной записью продавца
oauth	Аутентификация
ordercustomattributes	Пользовательские атрибуты для заказов
orders	Управление заказами
payments	Обработка платежей
payouts	Управление выплатами
refunds	Управление возвратами
sites	Интеграция с веб-сайтом
snippets	Интеграция с Square Online Code
subscriptions	Управление подписками
team	Управление персоналом
terminal	Управление Square Terminal
vendors	Управление поставщиками
webhooksubscriptions	Уведомления о событиях

Паттерн использования

Для оптимального взаимодействия с API Square через MCP:

1. Обнаружение: Используйте get_service_info для изучения доступных методов

   get_service_info(service: "catalog")
   

2. Понимание: Используйте get_type_info для изучения требований к параметрам

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

3. Выполнение: Используйте make_api_request для выполнения операции

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

Разработка и отладка

Использование MCP Inspector

MCP Inspector предоставляет визуальный интерфейс для тестирования:

# Build the project
npm run build

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

Рабочий процесс разработки

1. Клонируйте репозиторий
2. Установите зависимости: npm install
3. Запустите режим разработки: npm run watch
4. Запустите сервер: node dist/index.js start
5. Протестируйте изменения с помощью MCP Inspector

Участие в разработке

Этот репозиторий автоматически генерируется из спецификации OpenAPI Square. Хотя вклад приветствуется, обратите внимание, что изменения должны быть включены в генератор, который создаёт этот код. Пожалуйста, откройте issue для обсуждения предлагаемых изменений перед отправкой pull request.