Square

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

Square Model Context Protocol サーバー（ベータ版）

このプロジェクトは 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 ドキュメント にあります。既存の 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 クイックスタートガイド を参照してください。この設定を 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 と最適に対話するには：

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 仕様から自動生成されています。貢献は歓迎しますが、変更はこのコードを生成するジェネレーターに組み込む必要があることに注意してください。プルリクエストを送信する前に、提案された変更について議論するために issue を開いてください。