Square MCP Server Cursor IDE Setup 2026

How do you set up the Square MCP server in Cursor? Add an mcpServers entry pointing at Square's official remote server, https://mcp.squareup.com/mcp, using the mcp-remote proxy for OAuth, or run the local square-mcp-server package with a Square access token if you want a self-managed credential instead of a browser consent flow. Either path gives Cursor's AI direct access to your Square account's customers, orders, items, and payments data.

Square's MCP server is currently in Beta, published under Square's own GitHub organization at square/square-mcp-server. It is not a community reverse-engineering of the Square API — it is Square's own bridge between the Square REST API platform and MCP-compatible clients, and Square explicitly lists Cursor, Claude Desktop, Claude.ai, Goose, and Windsurf as supported clients.

What You Can Do With Square MCP in Cursor

Once connected, Cursor can:

Because the server exposes "programmatic access to everything the APIs offer" per Square's own documentation, the practical ceiling here is close to the full Square API surface — customers, orders, catalog, inventory, and payments — not a narrow fixed tool list like some single-purpose MCP servers ship with.

Beta Status: What That Actually Means

Square has not published a stable-release date for this server as of this writing. Beta here means the tool list, config shape, and even the exact package name could change between now and general availability — Square directs users to the GitHub repo for feedback and issue reports rather than a support ticket queue. Treat this the way you'd treat any beta payments-adjacent integration: fine for development, sandbox testing, and internal tooling; something to re-verify before wiring into a production workflow that touches live customer charges.

Prerequisites

Method 1: Remote Server via OAuth (Recommended)

This is Square's recommended path for most Cursor users — no access token to generate, copy, or rotate manually.

Step 1: Add the remote server to mcp.json

Square's remote server needs the mcp-remote proxy to bridge OAuth into Cursor's config format, the same pattern Atlassian's Rovo MCP Server and several other OAuth-based remote servers use:

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

Step 2: Restart Cursor and authorize

Restart Cursor completely. On first tool call, mcp-remote opens a browser window pointing at Square's OAuth consent screen. Sign in with your Square account and authorize the scopes the connection requests — Square's docs describe this as authorizing "only the scopes your application needs," meaning the consent screen should show a specific, readable list rather than a blanket grant.

Step 3: Verify

In Cursor chat, try:

List my Square locations

A response with your actual business location data (even a single default sandbox location) confirms the connection is live.

Method 2: Local Server With an Access Token

Use this if a browser OAuth flow isn't practical — CI, headless environments, a shared dev machine — or if your team's security policy prefers a self-managed, individually revocable token over a cached OAuth session.

Step 1: Generate a Square access token

1. Log into the Square Developer Dashboard
2. Open (or create) an application
3. Under Credentials, copy either the Sandbox Access Token (for testing against fake data) or the Production Access Token (for your live Square account)
4. Treat the production token like any other live payments credential — Square's dashboard lets you regenerate it if it leaks, but there's no scoped/restricted-key equivalent here the way Stripe offers restricted keys, so a leaked token has broad access to whatever your application's permissions cover

Step 2: Add the local server to mcp.json

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

Set "SANDBOX": "true" while testing — this points the server at Square's sandbox environment, where orders and payments are fake and safe to experiment with. Switch it to "false" (or your token to a production token) only once you've confirmed the workflows you're building behave the way you expect.

Step 3: Restart Cursor and test

Restart Cursor, then in chat:

Show me the items in my Square catalog

A real (or sandbox-seeded) catalog response confirms the local path is working.

Practical Workflows

Debugging a failed payment

Look up payment ID abc123 in Square and tell me its status, the order it's attached to, and any error codes on the transaction

Cross-referencing an order with inventory

Check order #4521 in Square, then tell me if the items on it are still in stock at the downtown location

Generating integration code against real data

Pull a real customer object from Square sandbox and write a TypeScript type for it based on the actual fields returned, not the API reference docs

Catalog audit

List all catalog items that don't have a price set, across all locations

Sandbox vs. Production: Don't Mix Them in One Session

Square's sandbox and production environments use different tokens and return structurally similar but data-wise completely separate results. A common mistake: testing a workflow against sandbox, confirming it looks right, then asking Cursor to "do the same thing" in a later message without explicitly telling it you've switched the mcp.json env to a production token. If you keep two server entries — square-sandbox and square-live — with different keys, it's much harder to accidentally run a write operation against live customer data while thinking you're still in sandbox.

{
  "mcpServers": {
    "square-sandbox": {
      "command": "npx",
      "args": ["square-mcp-server", "start"],
      "env": {
        "ACCESS_TOKEN": "your-sandbox-token",
        "SANDBOX": "true"
      }
    },
    "square-live": {
      "command": "npx",
      "args": ["square-mcp-server", "start"],
      "env": {
        "ACCESS_TOKEN": "your-production-token",
        "SANDBOX": "false"
      }
    }
  }
}

Troubleshooting

Server never appears in Cursor. Confirm the top-level key in mcp.json is mcpServers, the JSON is valid (one syntax error drops every server in the file, not just Square's), and — for the remote path — that mcp-remote isn't blocked by a corporate proxy that intercepts the OAuth redirect.

OAuth browser window never opens (remote path). Confirm Node.js 18+ is installed and that npx can reach the network. Some locked-down corporate machines block npx from fetching packages on first run; if mcp-remote itself fails to install, that's a network/proxy issue, not a Square-side problem.

"Unauthorized" on the local path. The access token is either expired, revoked, or you copied the sandbox token into a config with "SANDBOX": "false" (or vice versa) — a sandbox token will not authenticate against production and a production token returns confusing results against sandbox-shaped requests.

Beta tool suddenly missing or renamed. Because this server is Beta, Square can change tool names or the config shape between releases without the long deprecation windows a GA product would get. If a documented tool call stops working, check the GitHub repo's recent commits before assuming your config broke.

Catalog or inventory numbers look stale. This integration is pull-based like most MCP servers — Cursor fetches what you ask for at the moment you ask, it doesn't push live updates into an existing chat. Ask again rather than trusting an inventory count from earlier in a long conversation, especially right after a sale or manual adjustment in the Square dashboard.

Local package name changes on you. Because this is Beta software, don't be surprised if square-mcp-server gets renamed or restructured before GA. Check the official repo if npx square-mcp-server start stops resolving.

When Not to Use This

Be cautious about letting an AI-driven workflow issue real charges, refunds, or catalog price changes against a production Square account without a human confirming the exact object IDs and amounts first. A model that's confidently wrong about which order or customer it's operating on is a worse failure mode here than almost anywhere else on this site, since a mistaken write can move real money. Keep production writes to Square manual, or at minimum behind an explicit confirmation step, even after you trust the read-side workflows.

Frequently Asked Questions

Q: Is the Square MCP server official, or a community project?
A: Official. It's published under Square's own GitHub organization (square/square-mcp-server) and documented on Square's developer docs site, not a third-party reverse-engineering of the Square API.

Q: Is the Square MCP server ready for production use?
A: It's currently in Beta. It works against both sandbox and production Square accounts, but Square hasn't published a stable-release date, and the tool list or config shape could change before general availability. Treat production use with the same caution you'd apply to any beta integration that can touch live payments data.

Q: Should I use the remote OAuth server or the local package?
A: OAuth (remote) if you want to avoid managing a long-lived access token and are comfortable with a browser-based consent flow. The local package if you're in a headless environment (CI, a server without a browser), or your security policy prefers a self-managed, individually revocable credential over a cached OAuth session.

Q: Does Square offer a restricted or read-only key like Stripe does?
A: Not as a distinct key type in the same way Stripe's restricted keys work. A Square access token's permissions are tied to what your Developer Dashboard application is scoped to; there's no built-in "read-only MCP key" toggle documented for this server as of this writing. If you need a hard read-only boundary, scope the underlying Square application's permissions as narrowly as your workflow allows.

Q: Can this see multiple Square locations?
A: Yes — location data and inventory counts are per-location, and the server can query across whichever locations the authenticated account (OAuth) or access token (local) has access to. Ask for a specific location by name if your business runs more than one, since an unscoped query can return combined or ambiguous results.

Q: What happens if my sandbox and production configs get mixed up in the same mcp.json?
A: Nothing stops you from doing it, and that's the risk — a sandbox token under a "SANDBOX": "false" setting or a production token under "SANDBOX": "true" will produce confusing, wrong-environment results rather than a clear error. Keep sandbox and production as separate, distinctly named server entries (see the dual-config example above) so it's obvious which one a prompt is hitting.

Related Guides

Official docs cited