Square MCP Server

официальный

Сервер протокола контекста модели (MCP) для Square

Документация

Сервер протокола контекста модели Square (бета-версия)

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

Square Model Context Protocol Server MCP server

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

Начните работу с сервером Square MCP, используя 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/sse

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

Параметры конфигурации

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

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

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

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

Удалённый MCP

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

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

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

# 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 Quickstart Guide. Добавьте эту конфигурацию в ваш claude_desktop_config.json:

Удалённый MCP

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

Этот подход позволяет вам аутентифицироваться напрямую с учётными данными 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. Обратитесь к Square API Documentation для получения подробной информации о каждом сервисе:

Сервис	Описание
`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`	Уведомления о событиях

Шаблон использования

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

Обнаружение: Используйте get_service_info для изучения доступных методов
```
get_service_info(service: "catalog")
```
Понимание: Используйте get_type_info для изучения требований к параметрам
```
get_type_info(service: "catalog", method: "list")
```
Выполнение: Используйте 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

Процесс разработки

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

Участие в проекте

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