Square MCP Server

How to use

You connect with an MCP client to the Square MCP Server to explore available methods, understand parameter requirements, and execute API requests. Start the local server for development or use the hosted remote MCP server for a streamlined setup that handles authentication for you.

How to install

Prerequisites: you need Node.js and npm installed on your machine. You may also use npx for quick, one-off commands.

# Basic startup using local MCP server
npx square-mcp-server start

# With environment configuration (replace with your token and options)
ACCESS_TOKEN=YOUR_SQUARE_ACCESS_TOKEN SANDBOX=true npx square-mcp-server start

# For a local project path
npx /path/to/project/square-mcp-server

Configuration and runtime options

You can run the server in two ways: as a remote MCP server or as a local (stdio) MCP server. The remote MCP is hosted at a Square URL and handles OAuth authentication for you. The local MCP runs on your machine via npx and uses an access token you provide.

Quick start configuration example

{
  "mcpServers": {
    "square_api_mcp": {
      "type": "http",
      "name": "square_api_mcp",
      "url": "https://mcp.squareup.com/sse",
      "args": []
    },
    "square_mcp": {
      "type": "stdio",
      "name": "square_mcp",
      "command": "npx",
      "args": ["square-mcp-server", "start"],
      "env": {
        "ACCESS_TOKEN": "YOUR_SQUARE_ACCESS_TOKEN",
        "SANDBOX": "true"
      }
    }
  }
}

Security and tokens

Keep your Square access token secure. Do not commit tokens to version control. When using the local MCP, store tokens in environment variables and consider using a secret manager for production deployments.

Advanced usage with a hosted remote MCP

If you choose the hosted remote MCP, you can log in with your Square account directly and avoid managing access tokens manually. Use the hosted endpoint and follow standard OAuth flows supported by the remote MCP.

Development and debugging

When developing locally, you can build and test using the MCP Inspector to verify endpoint discovery, parameter requirements, and request execution. Start the server in development mode as described in the setup steps and use the inspector to validate your changes.

Notes and troubleshooting

If you encounter token or authentication issues, verify that the ACCESS_TOKEN value is correct and that SANDBOX or PRODUCTION flags align with your environment. For read-only testing, set DISALLOW_WRITES to true. Ensure the Square API version matches your integration requirements by setting SQUARE_VERSION.

Tools and capabilities

The Square MCP Server exposes tools to discover, describe, and execute API calls. You can discover available methods, learn parameter requirements, and perform API requests to Square services.

Usage pattern

1. Discover: Use the available discovery tool to list methods for a service like catalog.

2. Understand: Use the type information tool to learn required parameters for a method.

3. Execute: Use the API request tool to perform an operation, supplying the necessary parameters.

Development and debugging (Inspector)

# Build the project
npm run build

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

Contributing

Contributions are welcome. Changes should be reflected in the MCP code generator and tested with the inspector. Open issues to discuss proposed changes before submitting PRs.

get_service_info

Discover methods available for a service to understand what you can call and how to structure requests.

get_type_info

Fetch detailed parameter requirements for a specific method to prepare correct requests.

make_api_request

Execute API calls against Square services to perform operations.