Square

공식

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

Square MCP(으)로 무엇을 할 수 있나요?

Square API 메서드 살펴보기 — 어시스턴트에게 get_service_info를 사용하여 카탈로그나 결제와 같은 모든 Square 서비스에서 사용 가능한 작업을 탐색하도록 요청하세요.
요청 매개변수 이해하기 — 어시스턴트가 호출을 실행하기 전에 get_type_info를 통해 특정 API 메서드에 대한 자세한 매개변수 요구 사항을 조회하도록 하세요.
Square API 호출 실행하기 — 어시스턴트에게 make_api_request를 통해 재고 목록 조회나 주문 생성과 같은 작업을 수행하도록 지시하세요.
호스팅된 Square MCP에 연결하기 — 원격 서버 https://mcp.squareup.com/mcp에서 OAuth를 사용하여 Square 계정으로 인증하도록 AI 어시스턴트를 구성하세요.

호스팅형 MCP 서버

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

Claude Code, Codex, Cursor 등에 설치됩니다

문서

Square Model Context Protocol 서버 (베타)

이 프로젝트는 Model Context Protocol 표준을 따르며, AI 어시스턴트가 Square의 connect API와 상호작용할 수 있게 합니다.

대부분의 사용자는 호스팅 서버를 사용해야 합니다. Square는 https://mcp.squareup.com/mcp에서 OAuth 로그인을 지원하는 원격 MCP 서버를 운영합니다. AI 어시스턴트 설정 방법은 Square MCP 문서를 참조하세요. 이 저장소는 로컬 자체 호스팅 서버로, 직접 실행하려는 경우의 시작점입니다. 코드 변경은 Contributing 섹션에 설명된 생성기를 통해 이루어집니다.

Square Model Context Protocol Server MCP server

빠른 시작

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 문서에 있습니다. 기존 SSE 구성의 경우 이전 https://mcp.squareup.com/sse 엔드포인트도 계속 제공됩니다.

구성 옵션

환경 변수	용도	예시
`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가 설치된 컴퓨터에서 다음 URL을 클릭하여 Square 원격 MCP를 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 Quickstart Guide를 참조하세요. 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 서버는 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 Terminal 관리
`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 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를 사용하여 변경 사항 테스트

기여

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