Square Model Context Protocol Server (Beta)

Square Model Context Protocol Server（ベータ）

このプロジェクトはModel Context Protocol標準に準拠しており、AI アシスタントが Square の Connect API と連携できます。

ほとんどの方には、ホスト型サーバーのご利用をおすすめします。 Square は https://mcp.squareup.com/mcp で OAuth サインインを利用するリモート MCP サーバーを運用しています。AI アシスタントでのセットアップについては、Square MCP ドキュメントをご覧ください。このリポジトリはローカルのセルフホスト可能なサーバーであり、独自のコピーを実行したい場合の出発点となります。コードの変更は、「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	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 Server を設定するには、次の手順に従ってください。

リモート MCP

Goose に Square リモート MCP をインストールするには、Goose がインストールされているコンピューターで次の URL をクリックしてください。

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 は、Square API と連携するためのシンプルなツールセットを提供します。

ツール	説明	主な用途
get_service_info	サービスで利用可能なメソッドを確認	調査と検出
get_type_info	パラメーター要件の詳細を取得	リクエストの準備
make_api_request	Square への API 呼び出しを実行	操作の実行

サービスカタログ

Square MCP Server は、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 を最適に利用するには、次の手順に従います。

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 を使って変更をテストします

コントリビューション

このリポジトリは、Square の OpenAPI Specification から自動生成されています。コントリビューションを歓迎しますが、変更をこのコードの生成元となるジェネレーターにも反映する必要があります。プルリクエストを送信する前に、提案する変更について議論するため、イシューを作成してください。