mcpengine/servers/square/README.md

Square MCP Server

A comprehensive Model Context Protocol (MCP) server for Square, providing AI assistants with complete access to payment processing, point-of-sale operations, and business management. This server delivers 80 tools across payments, inventory, customers, and e-commerce workflows, plus 18 React-based UI applications.

Features

• Payment Processing: Create, capture, void, and refund payments with support for all payment methods
• Order Management: Create orders, manage line items, apply discounts, calculate taxes, and track fulfillment
• Customer Management: Full CRM with customer profiles, groups, segments, and marketing preferences
• Catalog & Inventory: Manage products, variations, modifiers, categories, and real-time inventory tracking
• Invoicing: Create, send, update, and track invoices with payment reminders
• Subscriptions: Manage recurring billing, subscription plans, and customer subscriptions
• Loyalty Programs: Create loyalty programs, track points, and manage rewards
• Team Management: Manage team members, roles, wage settings, and permissions
• Location Management: Handle multiple business locations and location-specific settings
• Booking & Appointments: Manage appointment calendars, bookings, and service catalog
• Dispute Handling: Track payment disputes, submit evidence, and manage chargebacks
• Refund Operations: Process full and partial refunds with automatic inventory adjustment
• 18 React Apps: Pre-built UI components for POS, inventory management, customer dashboards, and more
• Multi-Currency Support: Process payments in multiple currencies with automatic conversion
• Sandbox Testing: Full sandbox environment support for development and testing

Installation

npm install && npm run build

Environment Variables

Variable	Required	Description	Example
SQUARE_ACCESS_TOKEN	Yes	Your Square access token (sandbox or production)	EAAAEOuLQPTO1Z4...
SQUARE_ENVIRONMENT	No	Environment: sandbox or production (default: production)	sandbox

Getting Your Access Token

Production Token (Live Payments)

1. Create a Square Developer Account:

   • Go to developer.squareup.com
   • Click Sign Up or log in with your Square account
   • Complete the developer registration

2. Create an Application:

   • Go to Square Developer Dashboard
   • Click + Create App or New Application
   • Enter application name (e.g., "MCP Integration")
   • Select your Square account to associate with the app

3. Get Production Access Token:

   • In your application dashboard, click Production tab
   • Under Credentials, find Access Token
   • Click Show to reveal the token
   • Copy the entire token (starts with EAA...)

4. Set Environment Variables:

   export SQUARE_ACCESS_TOKEN="your_production_token_here"
   export SQUARE_ENVIRONMENT="production"
   

Sandbox Token (Testing)

1. Access Sandbox Credentials:

   • In your application dashboard
   • Click the Sandbox tab (not Production)
   • Under Credentials, find Sandbox Access Token
   • Click Show to reveal the token

2. Set Environment Variables:

   export SQUARE_ACCESS_TOKEN="your_sandbox_token_here"
   export SQUARE_ENVIRONMENT="sandbox"
   

3. Test Data:

   • Sandbox uses fake credit cards: 4111 1111 1111 1111 (Visa)
   • CVV: any 3 digits, Expiry: any future date
   • Postal code: any 5-digit ZIP
   • Full test card list

OAuth 2.0 (For Third-Party Apps)

If building an app for other Square merchants:

1. Enable OAuth: In app settings, enable OAuth
2. Set Redirect URL: Add your OAuth callback URL
3. Authorization Flow:
   • Direct user to: https://connect.squareup.com/oauth2/authorize?client_id={APP_ID}&scope={SCOPES}
   • User authorizes and redirects back with code
   • Exchange code for access token at /oauth2/token endpoint

Security Notes:

• Never commit access tokens to version control
• Production tokens have full access to real payment data
• Rotate tokens regularly and use OAuth for third-party integrations
• Sandbox and production tokens are completely separate

Required API Scopes

Square access tokens automatically include these permissions:

Payment Scopes:

• PAYMENTS_READ - View payment history and details
• PAYMENTS_WRITE - Process payments, refunds, and voids
• PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS - Split payments to multiple recipients

Order & Catalog Scopes:

• ORDERS_READ - View orders
• ORDERS_WRITE - Create and update orders
• ITEMS_READ - View catalog items and inventory
• ITEMS_WRITE - Manage products, variations, and inventory

Customer Scopes:

• CUSTOMERS_READ - View customer data
• CUSTOMERS_WRITE - Create and update customers
• MERCHANT_PROFILE_READ - View business information
• MERCHANT_PROFILE_WRITE - Update business settings

Additional Scopes:

• INVOICES_READ / INVOICES_WRITE - Manage invoices
• SUBSCRIPTIONS_READ / SUBSCRIPTIONS_WRITE - Manage subscriptions
• APPOINTMENTS_READ / APPOINTMENTS_WRITE - Manage bookings
• LOYALTY_READ / LOYALTY_WRITE - Manage loyalty programs
• TIMECARDS_READ / TIMECARDS_WRITE - Manage team time tracking
• DISPUTES_READ / DISPUTES_WRITE - Handle payment disputes
• GIFTCARDS_READ / GIFTCARDS_WRITE - Manage gift cards

OAuth Scope Format: When using OAuth, request specific scopes in the authorization URL (space-separated list).

Usage

stdio Mode (Default)

Add to your MCP client configuration (e.g., Claude Desktop):

{
  "mcpServers": {
    "square": {
      "command": "node",
      "args": [
        "/path/to/mcpengine-repo/servers/square/dist/index.js"
      ],
      "env": {
        "SQUARE_ACCESS_TOKEN": "your_token_here",
        "SQUARE_ENVIRONMENT": "sandbox"
      }
    }
  }
}

HTTP Mode

The server can also run as an HTTP endpoint:

export SQUARE_ACCESS_TOKEN="your_token_here"
export SQUARE_ENVIRONMENT="sandbox"
npm start -- --http --port 3000

Then configure your MCP client to connect to http://localhost:3000.

Coverage Manifest

Total API endpoints: ~150 (Square API v2)
Tools implemented: 80
Intentionally skipped: ~40 (gift cards, cash drawer, labor, terminal, devices, deprecated v1 endpoints)
Not yet covered: ~30 (bank accounts, payouts, cards on file, snippets, sites, mobile auth)
Coverage: 80/150 = 53%

Coverage Notes:

• ✅ Complete: Payments (8 tools), Orders (10 tools), Customers (9 tools), Catalog (9 tools), Inventory (7 tools), Invoices (8 tools), Subscriptions (7 tools), Locations (4 tools), Team Members (6 tools), Bookings (6 tools), Disputes (3 tools), Refunds (3 tools), Loyalty (8+ tools)
• ⏭️ Skipped: Gift cards (separate activation flow), cash drawer management, labor/shift tracking, terminal device pairing, deprecated v1 APIs, snippets/embeds
• 🚧 Planned: Bank account verification, payout schedules, saved payment methods (cards on file), marketing snippets, Square Sites integration, mobile authorization

Example Use Cases

• "Process a $49.99 payment for customer john@example.com"
• "Create a new product 'Organic Coffee Beans' with price $24.99"
• "List all orders from the last 7 days"
• "Add customer Sarah Johnson with email sarah@example.com"
• "Refund payment #xyz123 for $10.00"
• "Update inventory count for product SKU 'BEANS-001' to 50 units"
• "Create an invoice for $500 due in 30 days"
• "List all team members at the Downtown location"
• "Get today's payment summary across all locations"
• "Create a subscription plan for $29.99/month"

Architecture

The server uses Square API v2 (2024-12-18) with Bearer token authentication:

• Client: SquareClient with automatic idempotency key generation
• Tools: 13 tool modules with 80 total tools
• Apps: 18 React-based UI components
• Auth: HTTP Bearer Authentication (Authorization: Bearer {token})
• Pagination: Automatic cursor-based pagination
• Idempotency: Automatic UUID generation for idempotent operations
• Retry Logic: Built-in retry with exponential backoff (3 attempts, 1s delay)
• Rate Limits: Respects Square rate limits (varies by endpoint, typically 10-500 req/sec)
• API Version: 2024-12-18 (updates quarterly)

Links

• Square Developer Portal
• Square API Reference
• API Explorer
• OAuth Guide
• Testing Guide
• Sandbox Dashboard
• API Changelog
• Square Support