Square Model Context Protocol Server (square/square-mcp-server)

Square Model Context Protocol Server

https://github.com/square/square-mcp-server
Admin
A Model Context Protocol server that enables AI assistants to interact with Square's Connect API for...

Tokens:8,354
Snippets:48
Trust Score:7.6
Update:4 months ago
Show doc for...
Context Summary (auto-generated)
Raw
# Square MCP Server

The Square MCP Server is a Model Context Protocol (MCP) implementation that enables AI assistants to interact with Square's Connect API. Built on the MCP standard, this server provides a unified interface for accessing Square's complete API ecosystem, including payments processing, customer management, catalog operations, order management, inventory tracking, and over 30 other Square services. The server supports both local deployment with access token authentication and remote deployment via OAuth through Square's hosted MCP endpoint at `https://mcp.squareup.com/sse`.

The server exposes three primary MCP tools: `get_service_info` for discovering available API methods within a service, `get_type_info` for retrieving parameter requirements before making requests, and `make_api_request` for executing actual API calls. This design pattern encourages a discover-understand-execute workflow that helps AI assistants properly construct API requests. The server supports environment-based configuration for sandbox/production environments, read-only mode restrictions, and custom API versioning.

## Installation and Quick Start

The Square MCP Server can be started directly using npx without installation, or integrated into AI assistant configurations for Claude Desktop and Goose.

```bash
# Basic startup
npx square-mcp-server start

# With environment configuration for sandbox mode
ACCESS_TOKEN=YOUR_SQUARE_ACCESS_TOKEN SANDBOX=true npx square-mcp-server start

# Production mode with write restrictions
ACCESS_TOKEN=sq0atp-xxxxx PRODUCTION=true DISALLOW_WRITES=true npx square-mcp-server start

# Specify custom API version
SQUARE_VERSION=2025-04-16 ACCESS_TOKEN=sq0atp-xxxxx npx square-mcp-server start
```

## Claude Desktop Configuration

Configure the Square MCP Server in Claude Desktop by adding it to the mcpServers configuration in `claude_desktop_config.json`.

```json
{
  "mcpServers": {
    "mcp_square_api": {
      "command": "npx",
      "args": ["square-mcp-server", "start"],
      "env": {
        "ACCESS_TOKEN": "sq0atp-YOUR_ACCESS_TOKEN",
        "SANDBOX": "true"
      }
    }
  }
}
```

## Remote MCP Server Configuration

Square offers a hosted remote MCP server that uses OAuth authentication, eliminating the need to manage access tokens manually.

```json
{
  "mcpServers": {
    "mcp_square_api": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp.squareup.com/sse"]
    }
  }
}
```

## get_service_info Tool

Discovers available methods for a Square API service. Call this tool first to understand what operations are available before attempting API requests.

```typescript
// MCP Tool Call: get_service_info
// Input:
{
  "service": "catalog"
}

// Output: Available methods with descriptions
{
  "batchDeleteobjects": {
    "description": "Deletion is a cascading event such that all children of the targeted object are also deleted."
  },
  "batchGetobjects": {
    "description": "Each CatalogItem returned in the set includes all of its child information."
  },
  "batchUpsertobjects": {
    "description": "The target objects are grouped into batches and each batch is inserted/updated in an all-or-nothing manner."
  },
  "list": {
    "description": "The types parameter is specified as a comma-separated list of the CatalogObjectType values."
  },
  "searchObjects": {
    "description": "SearchCatalogObjects can search for any type of catalog objects."
  },
  "searchItems": {
    "description": "SearchCatalogItems can only search for items or item variations."
  },
  "upsertObject": {
    "description": "To ensure consistency, only one update request is processed at a time per seller account."
  },
  "getObject": {
    "description": "The returned object includes all of the relevant CatalogItem information."
  },
  "deleteObject": {
    "description": "Deletion is a cascading event such that all children of the targeted object are also deleted."
  },
  "info": {
    "description": "Catalog CatalogInfo operation"
  },
  "createImage": {
    "description": "Accepts HTTP multipart/form-data requests with a JSON part and an image file part."
  },
  "updateImage": {
    "description": "Accepts HTTP multipart/form-data requests with a JSON part and an image file part."
  },
  "updateItemModifierLists": {
    "description": "Catalog UpdateItemModifierLists operation"
  },
  "updateItemTaxes": {
    "description": "Catalog UpdateItemTaxes operation"
  }
}
```

## get_type_info Tool

Retrieves detailed type information and parameter requirements for a specific API method. Must be called before `make_api_request` to understand required and optional parameters.

```typescript
// MCP Tool Call: get_type_info
// Input:
{
  "service": "customers",
  "method": "create"
}

// Output: Type definitions with property details
[
  {
    "name": "CreateCustomerRequest",
    "properties": [
      {
        "name": "idempotency_key",
        "type": "string",
        "description": "A unique ID for the request, used to ensure idempotency.",
        "readOnly": false,
        "required": false
      },
      {
        "name": "given_name",
        "type": "string",
        "description": "The customer's given (first) name.",
        "readOnly": false,
        "required": false
      },
      {
        "name": "family_name",
        "type": "string",
        "description": "The customer's family (last) name.",
        "readOnly": false,
        "required": false
      },
      {
        "name": "company_name",
        "type": "string",
        "description": "The name of the customer's company.",
        "readOnly": false,
        "required": false
      },
      {
        "name": "email_address",
        "type": "string",
        "description": "The customer's email address.",
        "readOnly": false,
        "required": false
      },
      {
        "name": "phone_number",
        "type": "string",
        "description": "The customer's phone number.",
        "readOnly": false,
        "required": false
      },
      {
        "name": "address",
        "type": "Address",
        "description": "The customer's physical address.",
        "readOnly": false,
        "required": false
      }
    ]
  }
]
```

## make_api_request Tool - Payments Service

Execute payment operations including creating, listing, retrieving, updating, canceling, and completing payments.

```typescript
// MCP Tool Call: make_api_request - Create a payment
// Input:
{
  "service": "payments",
  "method": "create",
  "request": {
    "source_id": "cnon:card-nonce-ok",
    "idempotency_key": "unique-key-12345",
    "amount_money": {
      "amount": 1000,
      "currency": "USD"
    },
    "location_id": "LOCATION_ID",
    "note": "Payment for Order #1234"
  }
}

// Output: Created payment object
{
  "payment": {
    "id": "PAYMENT_ID",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z",
    "amount_money": {
      "amount": 1000,
      "currency": "USD"
    },
    "status": "COMPLETED",
    "source_type": "CARD",
    "location_id": "LOCATION_ID"
  }
}

// MCP Tool Call: make_api_request - List payments with filters
// Input:
{
  "service": "payments",
  "method": "list",
  "request": {
    "begin_time": "2024-01-01T00:00:00Z",
    "end_time": "2024-01-31T23:59:59Z",
    "sort_order": "DESC",
    "limit": 50
  }
}

// MCP Tool Call: make_api_request - Get specific payment
// Input:
{
  "service": "payments",
  "method": "get",
  "request": {
    "payment_id": "PAYMENT_ID"
  }
}

// MCP Tool Call: make_api_request - Cancel a payment
// Input:
{
  "service": "payments",
  "method": "cancel",
  "request": {
    "payment_id": "PAYMENT_ID"
  }
}
```

## make_api_request Tool - Customers Service

Manage customer profiles including creation, retrieval, updates, searches, and bulk operations.

```typescript
// MCP Tool Call: make_api_request - Create a customer
// Input:
{
  "service": "customers",
  "method": "create",
  "request": {
    "idempotency_key": "customer-create-001",
    "given_name": "John",
    "family_name": "Doe",
    "email_address": "john.doe@example.com",
    "phone_number": "+1-555-555-5555",
    "address": {
      "address_line_1": "123 Main Street",
      "locality": "San Francisco",
      "administrative_district_level_1": "CA",
      "postal_code": "94102",
      "country": "US"
    }
  }
}

// Output: Created customer object
{
  "customer": {
    "id": "CUSTOMER_ID",
    "created_at": "2024-01-15T10:30:00Z",
    "given_name": "John",
    "family_name": "Doe",
    "email_address": "john.doe@example.com",
    "phone_number": "+1-555-555-5555"
  }
}

// MCP Tool Call: make_api_request - Search customers
// Input:
{
  "service": "customers",
  "method": "search",
  "request": {
    "query": {
      "filter": {
        "email_address": {
          "exact": "john.doe@example.com"
        }
      }
    },
    "limit": 10
  }
}

// MCP Tool Call: make_api_request - Update customer
// Input:
{
  "service": "customers",
  "method": "update",
  "request": {
    "customer_id": "CUSTOMER_ID",
    "phone_number": "+1-555-555-9999",
    "note": "VIP customer"
  }
}

// MCP Tool Call: make_api_request - Bulk retrieve customers
// Input:
{
  "service": "customers",
  "method": "bulkGet",
  "request": {
    "customer_ids": ["CUSTOMER_ID_1", "CUSTOMER_ID_2", "CUSTOMER_ID_3"]
  }
}

// MCP Tool Call: make_api_request - List all customers with pagination
// Input:
{
  "service": "customers",
  "method": "list",
  "request": {
    "limit": 100,
    "sort_field": "CREATED_AT",
    "sort_order": "DESC"
  }
}
```

## make_api_request Tool - Catalog Service

Manage product catalogs including items, variations, categories, discounts, and taxes.

```typescript
// MCP Tool Call: make_api_request - Create catalog item
// Input:
{
  "service": "catalog",
  "method": "upsertObject",
  "request": {
    "idempotency_key": "catalog-item-001",
    "object": {
      "type": "ITEM",
      "id": "#coffee",
      "item_data": {
        "name": "Coffee",
        "description": "Freshly brewed coffee",
        "category_id": "CATEGORY_ID",
        "variations": [
          {
            "type": "ITEM_VARIATION",
            "id": "#coffee-small",
            "item_variation_data": {
              "item_id": "#coffee",
              "name": "Small",
              "pricing_type": "FIXED_PRICING",
              "price_money": {
                "amount": 250,
                "currency": "USD"
              }
            }
          },
          {
            "type": "ITEM_VARIATION",
            "id": "#coffee-large",
            "item_variation_data": {
              "item_id": "#coffee",
              "name": "Large",
              "pricing_type": "FIXED_PRICING",
              "price_money": {
                "amount": 350,
                "currency": "USD"
              }
            }
          }
        ]
      }
    }
  }
}

// MCP Tool Call: make_api_request - List catalog items
// Input:
{
  "service": "catalog",
  "method": "list",
  "request": {
    "types": "ITEM,ITEM_VARIATION,CATEGORY"
  }
}

// MCP Tool Call: make_api_request - Search catalog items
// Input:
{
  "service": "catalog",
  "method": "searchItems",
  "request": {
    "text_filter": "coffee",
    "product_types": ["REGULAR"],
    "limit": 20
  }
}

// MCP Tool Call: make_api_request - Get catalog object with related objects
// Input:
{
  "service": "catalog",
  "method": "getObject",
  "request": {
    "object_id": "CATALOG_ITEM_ID",
    "include_related_objects": true
  }
}

// MCP Tool Call: make_api_request - Batch upsert catalog objects
// Input:
{
  "service": "catalog",
  "method": "batchUpsertobjects",
  "request": {
    "idempotency_key": "batch-upsert-001",
    "batches": [
      {
        "objects": [
          {
            "type": "CATEGORY",
            "id": "#beverages",
            "category_data": {
              "name": "Beverages"
            }
          },
          {
            "type": "TAX",
            "id": "#sales-tax",
            "tax_data": {
              "name": "Sales Tax",
              "percentage": "8.5",
              "calculation_phase": "TAX_SUBTOTAL_PHASE"
            }
          }
        ]
      }
    ]
  }
}
```

## make_api_request Tool - Orders Service

Create, search, retrieve, update, and pay for orders.

```typescript
// MCP Tool Call: make_api_request - Create an order
// Input:
{
  "service": "orders",
  "method": "create",
  "request": {
    "idempotency_key": "order-001",
    "order": {
      "location_id": "LOCATION_ID",
      "line_items": [
        {
          "quantity": "2",
          "catalog_object_id": "ITEM_VARIATION_ID",
          "modifiers": []
        },
        {
          "quantity": "1",
          "name": "Custom Item",
          "base_price_money": {
            "amount": 500,
            "currency": "USD"
          }
        }
      ],
      "taxes": [
        {
          "catalog_object_id": "TAX_ID",
          "scope": "ORDER"
        }
      ],
      "discounts": [
        {
          "name": "10% Off",
          "percentage": "10",
          "scope": "ORDER"
        }
      ]
    }
  }
}

// Output: Created order
{
  "order": {
    "id": "ORDER_ID",
    "location_id": "LOCATION_ID",
    "state": "OPEN",
    "total_money": {
      "amount": 1215,
      "currency": "USD"
    },
    "total_tax_money": {
      "amount": 95,
      "currency": "USD"
    },
    "total_discount_money": {
      "amount": 130,
      "currency": "USD"
    }
  }
}

// MCP Tool Call: make_api_request - Search orders
// Input:
{
  "service": "orders",
  "method": "search",
  "request": {
    "location_ids": ["LOCATION_ID"],
    "query": {
      "filter": {
        "state_filter": {
          "states": ["OPEN", "COMPLETED"]
        },
        "date_time_filter": {
          "created_at": {
            "start_at": "2024-01-01T00:00:00Z",
            "end_at": "2024-01-31T23:59:59Z"
          }
        }
      },
      "sort": {
        "sort_field": "CREATED_AT",
        "sort_order": "DESC"
      }
    },
    "limit": 50
  }
}

// MCP Tool Call: make_api_request - Get order by ID
// Input:
{
  "service": "orders",
  "method": "get",
  "request": {
    "order_id": "ORDER_ID"
  }
}

// MCP Tool Call: make_api_request - Update an order
// Input:
{
  "service": "orders",
  "method": "update",
  "request": {
    "order_id": "ORDER_ID",
    "order": {
      "version": 1,
      "line_items": [
        {
          "quantity": "3",
          "catalog_object_id": "ITEM_VARIATION_ID"
        }
      ]
    }
  }
}

// MCP Tool Call: make_api_request - Calculate order totals
// Input:
{
  "service": "orders",
  "method": "calculate",
  "request": {
    "order": {
      "location_id": "LOCATION_ID",
      "line_items": [
        {
          "quantity": "2",
          "base_price_money": {
            "amount": 1000,
            "currency": "USD"
          }
        }
      ]
    }
  }
}
```

## make_api_request Tool - Inventory Service

Track and manage inventory counts, adjustments, and transfers across locations.

```typescript
// MCP Tool Call: make_api_request - Get inventory count
// Input:
{
  "service": "inventory",
  "method": "getCount",
  "request": {
    "catalog_object_id": "ITEM_VARIATION_ID",
    "location_ids": "LOCATION_ID_1,LOCATION_ID_2"
  }
}

// Output: Inventory counts
{
  "counts": [
    {
      "catalog_object_id": "ITEM_VARIATION_ID",
      "catalog_object_type": "ITEM_VARIATION",
      "state": "IN_STOCK",
      "location_id": "LOCATION_ID_1",
      "quantity": "50",
      "calculated_at": "2024-01-15T10:30:00Z"
    },
    {
      "catalog_object_id": "ITEM_VARIATION_ID",
      "catalog_object_type": "ITEM_VARIATION",
      "state": "IN_STOCK",
      "location_id": "LOCATION_ID_2",
      "quantity": "25",
      "calculated_at": "2024-01-15T10:30:00Z"
    }
  ]
}

// MCP Tool Call: make_api_request - Batch change inventory
// Input:
{
  "service": "inventory",
  "method": "batchChange",
  "request": {
    "idempotency_key": "inventory-change-001",
    "changes": [
      {
        "type": "ADJUSTMENT",
        "adjustment": {
          "catalog_object_id": "ITEM_VARIATION_ID",
          "from_state": "NONE",
          "to_state": "IN_STOCK",
          "location_id": "LOCATION_ID",
          "quantity": "100",
          "occurred_at": "2024-01-15T10:30:00Z"
        }
      }
    ]
  }
}

// MCP Tool Call: make_api_request - Batch retrieve inventory counts
// Input:
{
  "service": "inventory",
  "method": "batchGetcounts",
  "request": {
    "catalog_object_ids": ["ITEM_VAR_1", "ITEM_VAR_2", "ITEM_VAR_3"],
    "location_ids": ["LOCATION_ID"],
    "states": ["IN_STOCK", "SOLD"]
  }
}

// MCP Tool Call: make_api_request - Get inventory changes
// Input:
{
  "service": "inventory",
  "method": "batchGetchanges",
  "request": {
    "catalog_object_ids": ["ITEM_VARIATION_ID"],
    "location_ids": ["LOCATION_ID"],
    "updated_after": "2024-01-01T00:00:00Z"
  }
}
```

## make_api_request Tool - Locations Service

Manage business locations for multi-site operations.

```typescript
// MCP Tool Call: make_api_request - List all locations
// Input:
{
  "service": "locations",
  "method": "list",
  "request": {}
}

// Output: List of locations
{
  "locations": [
    {
      "id": "LOCATION_ID_1",
      "name": "Main Store",
      "address": {
        "address_line_1": "123 Main St",
        "locality": "San Francisco",
        "administrative_district_level_1": "CA",
        "postal_code": "94102",
        "country": "US"
      },
      "timezone": "America/Los_Angeles",
      "status": "ACTIVE",
      "created_at": "2023-01-01T00:00:00Z"
    }
  ]
}

// MCP Tool Call: make_api_request - Get main location
// Input:
{
  "service": "locations",
  "method": "get",
  "request": {
    "location_id": "main"
  }
}

// MCP Tool Call: make_api_request - Create a new location
// Input:
{
  "service": "locations",
  "method": "create",
  "request": {
    "location": {
      "name": "Downtown Store",
      "address": {
        "address_line_1": "456 Market St",
        "locality": "San Francisco",
        "administrative_district_level_1": "CA",
        "postal_code": "94103",
        "country": "US"
      },
      "business_hours": {
        "periods": [
          {
            "day_of_week": "MON",
            "start_local_time": "09:00:00",
            "end_local_time": "17:00:00"
          }
        ]
      }
    }
  }
}

// MCP Tool Call: make_api_request - Update location
// Input:
{
  "service": "locations",
  "method": "update",
  "request": {
    "location_id": "LOCATION_ID",
    "location": {
      "name": "Updated Store Name",
      "description": "Our flagship location"
    }
  }
}
```

## Available Services Reference

The Square MCP Server provides access to the complete Square API ecosystem through the following services.

```typescript
// All available services (use lowercase in service parameter)
const availableServices = [
  "applepay",           // Apple Pay integration
  "bankaccounts",       // Bank account management
  "bookingcustomattributes", // Custom attributes for bookings
  "bookings",           // Appointment booking management
  "cards",              // Payment card management
  "cashdrawers",        // Cash drawer management
  "catalog",            // Catalog management (items, categories)
  "checkout",           // Checkout and payment processing
  "customercustomattributes", // Custom attributes for customers
  "customergroups",     // Customer grouping
  "customersegments",   // Customer segmentation
  "customers",          // Customer management
  "devices",            // Square device management
  "disputes",           // Payment dispute handling
  "events",             // Event tracking
  "giftcardactivities", // Gift card activity tracking
  "giftcards",          // Gift card management
  "inventory",          // Inventory tracking
  "invoices",           // Invoice management
  "labor",              // Workforce management
  "locationcustomattributes", // Custom attributes for locations
  "locations",          // Location management
  "loyalty",            // Loyalty program management
  "merchantcustomattributes", // Custom attributes for merchants
  "merchants",          // Merchant account management
  "oauth",              // Authentication
  "ordercustomattributes", // Custom attributes for orders
  "orders",             // Order management
  "payments",           // Payment processing
  "payouts",            // Payout management
  "refunds",            // Refund management
  "sites",              // Website integration
  "snippets",           // Square Online Code integration
  "subscriptions",      // Subscription management
  "team",               // Staff management
  "terminal",           // Square Terminal management
  "vendors",            // Supplier management
  "webhooksubscriptions" // Event notifications
];

// Example: Discovering refunds service methods
// MCP Tool Call: get_service_info
{
  "service": "refunds"
}

// Example: Getting type info for creating a refund
// MCP Tool Call: get_type_info
{
  "service": "refunds",
  "method": "create"
}
```

## Environment Configuration

Configure the server behavior using environment variables for different deployment scenarios.

```bash
# Environment Variables Reference
export ACCESS_TOKEN="sq0atp-xxxxx"     # Square API access token (required for local)
export SANDBOX="true"                   # Use sandbox environment (default: false)
export PRODUCTION="true"                # Use production environment (default: true)
export DISALLOW_WRITES="true"           # Restrict to read-only operations
export SQUARE_VERSION="2025-04-16"      # Specify Square API version

# Sandbox mode for testing
ACCESS_TOKEN=sq0atp-sandbox-token SANDBOX=true npx square-mcp-server start

# Production read-only mode (safe for data exploration)
ACCESS_TOKEN=sq0atp-prod-token DISALLOW_WRITES=true npx square-mcp-server start

# Error when write operation attempted in read-only mode
{
  "error": "Write operations are not allowed in this environment. Please set DISALLOW_WRITES to false to enable write operations. Attempted operation: payments.create"
}
```

## Development and Testing

Use MCP Inspector for visual testing and debugging of the Square MCP Server.

```bash
# Build the project
npm install
npm run build

# Start development mode with watch
npm run watch

# Run with MCP Inspector for visual testing
npx @modelcontextprotocol/inspector node dist/index.js start

# Run server directly
node dist/index.js start

# Install command for automatic Goose and Claude configuration
npx square-mcp-server install

# Get Goose installation URL
npx square-mcp-server get-goose-url
```

## Summary

The Square MCP Server enables AI assistants to perform comprehensive e-commerce and payment operations through Square's API ecosystem. Primary use cases include payment processing workflows (creating, capturing, and managing payments), customer relationship management (creating profiles, searching, and managing customer data), product catalog management (items, variations, categories, taxes, and discounts), order management (creating, updating, and fulfilling orders), inventory tracking (stock levels, adjustments, and transfers across locations), and business operations (locations, team management, and reporting). The three-tool pattern (discover, understand, execute) ensures AI assistants can properly construct API requests without prior knowledge of Square's API structure.

Integration patterns typically involve first calling `get_service_info` to discover available methods, then `get_type_info` to understand required parameters, and finally `make_api_request` to execute operations. For production deployments, use the remote MCP server at `https://mcp.squareup.com/sse` with OAuth authentication for simplified credential management. For development and testing, use sandbox mode with `SANDBOX=true` to safely test operations without affecting production data. The `DISALLOW_WRITES=true` option provides an additional safety layer for read-only exploration of merchant data. All API responses follow Square's standard response format, and errors include detailed information for troubleshooting.