<Subheading>The Square Model Context Protocol (MCP) server implements the [Model Context Protocol](https://modelcontextprotocol.io) standard, providing a bridge between AI assistants and the Square REST API platform.</Subheading>


## Overview

<Info>
The Square MCP server is currently in Beta. To provide feedback or report bugs, open [GitHub issues](https://github.com/square/square-mcp-server/issues).
</Info>

To view the MCP server source or contribute to the project, see [GitHub - square/square-mcp-server](https://github.com/square/square-mcp-server/).

You can configure your AI agent to use the Square MCP server hosted by Block as a remote server or you can set up and run the server locally for your AI agent's use. For information about running the Square MCP server locally, see [Local Square MCP server quickstart](#local-server-quickstart).

## Square MCP server

The Square remote MCP server is hosted at:

```
https://mcp.squareup.com/mcp
```

### MCP server tools

The Square MCP server connects your AI tools directly to the full Square API platform, giving you programmatic access to everything the APIs offer—customers, orders, items, and more. Use it to power natural language queries, generate code, and accelerate development with AI assistance.

Square recommends using the remote MCP server, which supports OAuth login with more control and granular permissions. This lets you securely sign in with your Square account and authorize only the scopes your application needs, with no manual token management required.

For testing, you can run a local instance configured to access a seller's Sandbox environment. Remote instances only access production resources.

<Important>
Square recommends that you become familiar with the server and test your prompts against a Square account Sandbox environment before using it in production.
</Important>

## Integration with AI assistants

The Square MCP server works with many different AI assistants including:

* [Claude.ai](https://claude.ai)
* [Claude Desktop](https://claude.ai/download)
* [Goose](https://block.github.io/goose/)
* [Cursor](https://www.cursor.com/)
* [Windsurf](https://codeium.com/windsurf)

## Integrate with Claude.ai

Add the Square MCP server to Claude.

### For Claude Enterprise & Teams (owners and primary owners)

1. Navigate to **Settings > Integrations** (for Teams) or **Settings > Data management** (for Enterprise).
1. In the **Integrations** section, choose **Add more**.
1. Add the Square MCP server URL: `https://mcp.squareup.com/mcp`.
1. To finish configuring your integration, choose **Add**.

### For Claude Max

1. Navigate to **Settings > Profile**.
1. In the **Integrations** section, choose **Add more**.
1. Add the Square MCP server URL: `https://mcp.squareup.com/mcp`.
1. To finish configuring your integration, choose **Add**.

### Enable the Square integration

1. Open a chat with Claude.
2. In the chat interface, access the **Search and tools** menu.
3. Choose **Connect** to authenticate with your Square account.
4. After connecting, use the same menu to enable specific Square tools.

## Integrate with Claude Desktop

### Remote MCP

Add an entry to `claude_desktop_config.json` as shown in the following example:

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

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

### Local MCP

Add an entry to `claude_desktop_config.json` as shown in the following example:

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

## Integrate with Goose

[Install Goose](https://block.github.io/goose/docs/getting-started/installation) and then configure the Square MCP server as an extension for the Goose Desktop and Goose CLI. The Goose Desktop and CLI share the same configuration file so you only need to configure the MCP server once.

### Remote MCP server

To install the Square remote MCP server in Goose, click the [Open 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) link on any computer with Goose installed, choose **Open Goose**, and then choose **OK** to confirm the extension installation. You can also copy and paste the URL into your browser's address bar.

### Local MCP server

To install the Square remote MCP server in Goose, run the following command:

```bash
npx square-mcp-server install           # Auto-install local MCP for Goose
npx square-mcp-server get-goose-url     # Output a manual config URL
```

To learn more about using the Square MCP server with Goose, see [Square MCP Extension](https://block.github.io/goose/docs/tutorials/square-mcp).

## Integrate with Cursor

To connect [Cursor](https://www.cursor.com/) with the Square MCP server, following the instructions for a remote or local MCP server.

### Remote MCP server

Choose `Type`: "Command" and in the `Command` field, enter the following (recommended for OAuth authentication):

```
npx mcp-remote https://mcp.squareup.com/mcp
```

This allows you to log in with your Square account directly instead of managing access tokens.

### Local MCP server

Choose `Type`: "Command" and in the `Command` field, enter the following:

```
npx square-mcp-server start
```

## Integrate with Windsurf

Connect the Square MCP server to [Windsurf](https://codeium.com/windsurf) by editing the [`mcp_config.json` file](https://docs.codeium.com/windsurf/mcp):

### Remote MCP server

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

Using the remote MCP server enables OAuth authentication, allowing you to connect with your Square account credentials without managing access tokens.
<Info>

Square maintains an allowlist of MCP clients in order to protect against malicious client registration attempts. If you want your client added to the allowlist, please request an addition in the [Square developer forum](https://developer.squareup.com/forums/c/mcp/14).
</Info>

### Local MCP server

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

---


<a id="local-server-quickstart"></a>
## Local Square MCP server quickstart

To run a local instance, you need to have [Node.js](https://nodejs.org/en/download) installed. You can then set up and run the Square MCP server with a single command:

```bash
npx square-mcp-server start
```

To configure environment variables inline:

```bash
ACCESS_TOKEN=YOUR_SQUARE_ACCESS_TOKEN SANDBOX=true npx square-mcp-server start
```

To configure environment variables for local development:

```bash
npx /path/to/project/square-mcp-server
```

<Info>
You need your Square access token. For more information, see [Access Tokens and Other Square Credentials](https://developer.squareup.com/docs/build-basics/access-tokens).
</Info>

### Local configuration

Set the following environment variables as needed:

<StickyTable>

| Variable             | Purpose                              | Example                        |
|----------------------|--------------------------------------|--------------------------------|
| `ACCESS_TOKEN`       | Your Square API access token          | `ACCESS_TOKEN=sq0atp-...`      |
| `SANDBOX`            | Use the Square sandbox environment        | `SANDBOX=true`                 |
| `PRODUCTION`         | Use the Square production environment     | `PRODUCTION=true`              |
| `DISALLOW_WRITES`    | Restrict to read-only operations      | `DISALLOW_WRITES=true`         |
| `SQUARE_VERSION`     | Specify the Square API version            | `SQUARE_VERSION=2025-04-16`    |

</StickyTable>