Square

A Model Context Protocol (MCP) server for square

Square Model Context Protocol Server (Beta)

This project follows the Model Context Protocol standard, allowing AI assistants to interact with Square's connect API.

Quick Start

Get up and running with the Square MCP server using 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

Replace YOUR_SQUARE_ACCESS_TOKEN with your actual Square access token. You can obtain your access token by following the guide at Square Access Tokens. You can also set environment variables before running the command.

Remote MCP Server

Square now offers a hosted remote MCP server at:

https://mcp.squareup.com/sse

The remote MCP is recommended as it uses OAuth authentication, allowing you to log in with your Square account directly without having to create or manage access tokens manually.

Configuration Options

Environment VariablePurposeExample
ACCESS_TOKENYour Square API access tokenACCESS_TOKEN=sq0atp-...
SANDBOXUse Square sandbox environmentSANDBOX=true
PRODUCTIONUse Square production environmentPRODUCTION=true
DISALLOW_WRITESRestrict to read-only operationsDISALLOW_WRITES=true
SQUARE_VERSIONSpecify Square API versionSQUARE_VERSION=2025-04-16

Integration with AI Assistants

Goose Integration

To configure the Square MCP Server with Goose:

Remote MCP

To install the Square remote MCP in Goose, click this URL on a computer where Goose is installed:

goose://extension?cmd=npx&arg=mcp-remote&arg=https%3A%2F%2Fmcp.squareup.com%2Fsse&id=square_mcp_production_remote&name=Square%20MCP%20Remote&description=Square%20Production%20MCP%20Remote

Or copy and paste the URL into your browser's address bar.

# Automatic installation
npx square-mcp-server install

# Get URL for manual installation
npx square-mcp-server get-goose-url

The install command automatically updates your Goose configuration.

Claude Desktop Integration

For Claude Desktop integration, see the Model Context Protocol Quickstart Guide. Add this configuration to your claude_desktop_config.json:

Remote MCP

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

This approach allows you to authenticate directly with your Square account credentials without needing to manage access tokens.

Local MCP

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

Tool Reference

The Square MCP Server provides a streamlined set of tools for interacting with Square APIs:

ToolDescriptionPrimary Use
get_service_infoDiscover methods available for a serviceExploration and discovery
get_type_infoGet detailed parameter requirementsRequest preparation
make_api_requestExecute API calls to SquarePerforming operations

Service Catalog

Square MCP Server provides access to Square's complete API ecosystem. Check out the Square API Documentation for detailed information about each service:

ServiceDescription
applepayApple Pay integration
bankaccountsBank account management
bookingcustomattributesCustom attributes for bookings
bookingsAppointment booking management
cardsPayment card management
cashdrawersCash drawer management
catalogCatalog management (items, categories, etc.)
checkoutCheckout and payment processing
customercustomattributesCustom attributes for customers
customergroupsCustomer grouping
customersegmentsCustomer segmentation
customersCustomer management
devicesSquare device management
disputesPayment dispute handling
eventsEvent tracking
giftcardactivitiesGift card activity tracking
giftcardsGift card management
inventoryInventory tracking
invoicesInvoice management
laborWorkforce management
locationcustomattributesCustom attributes for locations
locationsLocation management
loyaltyLoyalty program management
merchantcustomattributesCustom attributes for merchants
merchantsMerchant account management
oauthAuthentication
ordercustomattributesCustom attributes for orders
ordersOrder management
paymentsPayment processing
payoutsPayout management
refundsRefund management
sitesWebsite integration
snippetsSquare Online Code integration
subscriptionsSubscription management
teamStaff management
terminalSquare Terminal management
vendorsSupplier management
webhooksubscriptionsEvent notifications

Usage Pattern

For optimal interaction with the Square API through MCP:

  1. Discover: Use get_service_info to explore available methods

    get_service_info(service: "catalog")
    
  2. Understand: Use get_type_info to learn parameter requirements

    get_type_info(service: "catalog", method: "list")
    
  3. Execute: Use make_api_request to perform the operation

    make_api_request(service: "catalog", method: "list", request: {})
    

Development and Debugging

Using MCP Inspector

The MCP Inspector provides a visual interface for testing:

# Build the project
npm run build

# Start the inspector with the Square MCP Server
npx @modelcontextprotocol/inspector node dist/index.js start

Development Workflow

  1. Clone the repository
  2. Install dependencies: npm install
  3. Start development mode: npm run watch
  4. Run the server: node dist/index.js start
  5. Test your changes using the MCP Inspector

Contributing

This repository is auto-generated from Square's OpenAPI Specification. While contributions are welcome, please note that changes will need to be incorporated into the generator that produces this code. Please open an issue to discuss proposed changes before submitting a pull request.

Related Servers