Square MCP Server

공식

Square를 위한 모델 컨텍스트 프로토콜(MCP) 서버

GitHub

100

문서

Square 모델 컨텍스트 프로토콜 서버 (베타)

이 프로젝트는 모델 컨텍스트 프로토콜 표준을 따르므로, AI 어시스턴트가 Square의 connect API와 상호 작용할 수 있습니다.

Square Model Context Protocol Server MCP server

빠른 시작

npx를 사용하여 Square MCP 서버를 빠르게 실행하세요:

# 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 액세스 토큰 가이드를 따라 액세스 토큰을 얻을 수 있습니다. 명령을 실행하기 전에 환경 변수를 설정할 수도 있습니다.

원격 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`

AI 어시스턴트와의 통합

Goose 통합

Goose와 Square MCP 서버를 구성하려면:

원격 MCP

Goose에 Square 원격 MCP를 설치하려면 Goose가 설치된 컴퓨터에서 이 URL을 클릭하세요:

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 통합에 대해서는 모델 컨텍스트 프로토콜 빠른 시작 가이드를 참조하세요. 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 서버는 Square API와 상호 작용하기 위한 간소화된 도구 세트를 제공합니다:

도구	설명	주요 용도
`get_service_info`	서비스에 사용 가능한 메서드 검색	탐색 및 발견
`get_type_info`	자세한 매개변수 요구 사항 확인	요청 준비
`make_api_request`	Square에 대한 API 호출 실행	작업 수행

서비스 카탈로그

Square MCP 서버는 Square의 전체 API 생태계에 대한 액세스를 제공합니다. 각 서비스에 대한 자세한 정보는 Square API 문서를 확인하세요:

서비스	설명
`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 터미널 관리
`vendors`	공급업체 관리
`webhooksubscriptions`	이벤트 알림

사용 패턴

MCP를 통한 Square API와의 최적의 상호 작용을 위해:

발견: 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 인스펙터 사용

MCP 인스펙터는 테스트를 위한 시각적 인터페이스를 제공합니다:

# 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 인스펙터를 사용하여 변경 사항 테스트

기여

이 리포지토리는 Square의 OpenAPI 사양에서 자동 생성됩니다. 기여는 환영하지만, 변경 사항은 이 코드를 생성하는 생성기에 통합되어야 합니다. 풀 리퀘스트를 제출하기 전에 이슈를 열어 제안된 변경 사항을 논의해 주세요.