🛍️ Squarespace MCP

Connect your Squarespace store directly to your favorite AI assistants.

Whether you use Claude Desktop, Cursor, Gemini CLI, or Gemini Spark, Squarespace MCP gives your AI the context it needs to answer questions about your store, analyze sales, check stock levels, and manage your catalog—all through simple, natural conversation.

✨ What can you ask your AI?

Once connected, you can ask questions and give instructions in plain English:

📦 Inventory & Stock: "Which product variants are running low on stock?" or "Do we have any out-of-stock items right now?"
🛍️ Orders & Fulfillment: "Show me all pending orders from this past weekend" or "Check the status of order #10042."
🏷️ Discounts & Sales: "What discount codes are currently active?" or (with write access) "Create a 15% off discount code 'SPRING15' valid until Friday."
👥 Customers & Contacts: "Look up customer details for alex@example.com" or "Find our top 10 customers by total spend."
📈 Store Performance: "Summarize transaction volume and sales for this past month."

🛡️ Safe by Default: Squarespace MCP starts in 100% read-only mode. Your AI can look up orders, inventory, and analytics, but it cannot modify or delete anything in your store unless you explicitly enable write mode. Credential storage depends on the selected authentication mode; see Security & Privacy.

🚀 Quick Start (Choose Your Setup)

Getting started takes less than 3 minutes. Pick how you prefer to use AI:

If you use...	Recommended Setup	How it works
Claude Desktop	Claude Desktop Setup	Runs locally on your computer with `npx`
Cursor / VS Code	Cursor & IDE Setup	Runs locally on your computer with `npx`
Gemini CLI	Gemini CLI Setup	Runs locally on your computer with `npx`
Gemini Spark (Web)	Gemini Spark Setup	Connects via a hosted HTTPS endpoint with OAuth

🔑 Step 1: Get Your Squarespace API Key

To let your AI interact with your store, create a secure API key:

Log in to your Squarespace Dashboard.
Navigate to Settings → Developer Tools (or Advanced) → Developer API Keys.
Click Generate Key.
Name your key (e.g., Squarespace MCP AI).
Choose your permissions:
- Recommended for general use (Read-Only): Check Read for Products, Inventory, Orders, and Profiles / Contacts.
- If you plan to use write actions later: Check Read and Write for the specific areas you want your AI to manage.
Click Generate Key and copy the key immediately (Squarespace will only show it once).

Note

Squarespace Developer API Keys are available on plans that support custom commerce integrations (typically Commerce Advanced). Learn more in the Squarespace Authentication Guide.

💻 Local Desktop Setup (Claude, Cursor, Gemini CLI)

Local setups run directly on your computer. You only need Node.js 24 or newer installed.

🟣 Claude Desktop

Add this configuration to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "squarespace": {
      "command": "npx",
      "args": ["-y", "@florasync/squarespace-mcp@0.1.0"],
      "env": {
        "SQUARESPACE_API_KEY": "YOUR_SQUARESPACE_API_KEY_HERE"
      }
    }
  }
}

Restart Claude Desktop, and you'll see a hammer icon 🔨 with Squarespace tools ready to use!

🔵 Gemini CLI / Antigravity CLI

Add this to ~/.gemini/settings.json or your project's .gemini/settings.json:

{
  "mcpServers": {
    "squarespace": {
      "command": "npx",
      "args": ["-y", "@florasync/squarespace-mcp@0.1.0"],
      "env": {
        "SQUARESPACE_API_KEY": "YOUR_SQUARESPACE_API_KEY_HERE"
      },
      "timeout": 30000,
      "trust": false
    }
  }
}

🟢 Cursor & IDE Setup

In Cursor, open Settings → Features → MCP Servers → Add New MCP Server:

Name: squarespace
Type: command
Command: npx -y @florasync/squarespace-mcp@0.1.0
Environment Variables: SQUARESPACE_API_KEY=YOUR_SQUARESPACE_API_KEY_HERE

Or create .cursor/mcp.json in your workspace:

{
  "mcpServers": {
    "squarespace": {
      "command": "npx",
      "args": ["-y", "@florasync/squarespace-mcp@0.1.0"],
      "env": {
        "SQUARESPACE_API_KEY": "YOUR_SQUARESPACE_API_KEY_HERE"
      }
    }
  }
}

⚡ Quick Command-Line Test

You can also run the server directly in your terminal to verify your connection:

SQUARESPACE_API_KEY="your-squarespace-api-key" \
  npx -y @florasync/squarespace-mcp@0.1.0

🌐 Gemini Spark (Web App)

Because Gemini Spark runs in Google's cloud web app, it cannot run npx commands on your computer. Instead, it connects via an HTTPS endpoint using standard OAuth 2.1 and encrypted credential tokens.

Local MCP Client (Claude, Cursor) ──stdio──> npx @florasync/squarespace-mcp ──Bearer──> Squarespace API

Gemini Spark (Google Web App)     ──HTTPS──> Hosted Cloud Run Service       ──Bearer──> Squarespace API
                                                      │
                                                      └─ User enters Squarespace key on secure web login

How to connect Gemini Spark:

Deploy the container in OAuth mode to Google Cloud Run. Follow our step-by-step Google Cloud Run Deployment Guide.
In the Gemini web app, go to Settings & help → Connected Apps.
Under Custom apps for Spark, enter your deployed URL (e.g. https://your-service.run.app/mcp).
Spark automatically connects and opens a secure authorization page.
Paste your Squarespace API key. The server validates your key directly with Squarespace and you're ready to chat!

HTTP Authentication Modes

Choose the mode explicitly with AUTHMODE. Existing deployments with MCP_TOKEN_SECRET and no AUTHMODE continue using OAuth. Without either setting, HTTP mode defaults to insecure-env and requires MCPAPIKEY.

Mode	Caller authenticates with	Squarespace credential
`oauth`	A bearer token issued after browser consent and PKCE	Each user enters their own credential at login; encrypted into their tokens
`insecure-env`	The shared `MCPAPIKEY` bearer key	Server environment: `SQUARESPACE_API_KEY` or `SQUARESPACE_ACCESS_TOKEN`
`secure-sqlite`	An API key whose bcrypt hash is stored in SQLite	Server environment: `SQUARESPACE_API_KEY` or `SQUARESPACE_ACCESS_TOKEN`

OAuth mode supports browser login and discovery. Both API-key modes require a client that can send a configured bearer token; they do not expose the OAuth login endpoints. Every caller with a valid MCP API key accesses the server-configured Squarespace store. Keep the inbound MCP key separate from the outbound Squarespace credential.

Build the current source with Node.js 24 or Docker. The published 0.1.0 image predates these authentication and browser-login fixes:

docker build -t squarespace-mcp .
docker run --rm -p 3000:3000 \
  -e AUTHMODE=oauth \
  -e MCP_TOKEN_SECRET \
  -e MCP_PUBLIC_URL=http://localhost:3000/mcp \
  squarespace-mcp

Set MCP_TOKEN_SECRET securely in your shell before running the command. For API-key access, set MCPAPIKEY and SQUARESPACE_API_KEY in your shell, then run:

docker run --rm -p 3000:3000 \
  -e AUTHMODE=insecure-env -e MCPAPIKEY -e SQUARESPACE_API_KEY \
  -e MCP_PUBLIC_URL=http://localhost:3000/mcp \
  squarespace-mcp

For SQLite-backed API keys, set INITAPIKEY to the initial caller key and provide persistent storage. Later boots ignore INITAPIKEY when the database already exists:

docker run --rm -p 3000:3000 -v squarespace-mcp-data:/data \
  -e AUTHMODE=secure-sqlite -e INITAPIKEY -e SQUARESPACE_API_KEY \
  -e MCP_PUBLIC_URL=http://localhost:3000/mcp \
  squarespace-mcp

Cloud Run's local filesystem is ephemeral, so the named Docker volume example is for hosts with persistent storage. Use the OAuth Cloud Run guide for the existing deployment. SQLite key storage does not provide a shared revocation service for the OAuth mode.

✍️ Enabling Write Mode (Optional)

By default, the server runs in safe read-only mode. If you'd like your AI to perform actions like adjusting inventory, creating discounts, or updating products:

In CLI / npx: Add --read-write to the command arguments:

SQUARESPACE_API_KEY="your-key" npx -y @florasync/squarespace-mcp@0.1.0 --read-write

In client JSON configs: Add "--read-write" to the "args" array:

"args": ["-y", "@florasync/squarespace-mcp@0.1.0", "--read-write"]

In Cloud Run / Remote deployments: Set the environment variable:
```
SQUARESPACE_MCP_READ_ONLY=false
```

🧰 What It Supports (52 Operations)

Squarespace MCP provides 52 official operations generated directly from Squarespace's Commerce OpenAPI specification (24 read-only, 28 write):

Area	Capabilities	Read-Only Tools	Write Tools (Requires `--read-write`)
Products v2	Physical, service, and digital products, variants, images, sorting	Browse products, view variants, check image status	Create/update/delete products, variants, and images
Inventory	Real-time stock counts and quantity tracking	Check stock levels, view variant quantities	Add, subtract, or set stock levels
Orders	Full order lifecycle management	List recent orders, search orders, get order details	Import orders, fulfill orders with tracking info
Discounts	Promo codes and automated store discounts	List active discounts, inspect discount rules	Create, update, or delete discount codes
Contacts	Customer directory and address books	Query contacts, search by email, view addresses	Create, update, or remove customer contacts
Analytics	Customer purchase history and metrics	Fetch per-contact transaction summaries	(Read-only query)
Transactions	Financial ledger and payment documents	Retrieve transaction documents and settlement info	(Read-only)
Website Identity	Site details and authenticated user profile	Inspect site metadata and member permissions	(Read-only)
Profiles	Legacy customer profile records	Read legacy profile data	(Read-only)
Webhooks	Real-time event notifications	List active webhook subscriptions	Create, test, rotate secrets, and delete subscriptions

Note

API Scope Boundary: This server integrates with Squarespace's official Commerce APIs. Squarespace does not offer public APIs for editing general page layouts, blog posts, form blocks, or custom CSS, so those operations are not included.

🔒 Security & Privacy

We take the security of your store seriously:

Never logs credentials: API keys and tokens are strictly scrubbed from logs and error messages.
Mode-specific storage: OAuth mode encrypts per-user credentials into client-held tokens. SQLite mode stores bcrypt hashes of inbound MCP keys; outbound Squarespace credentials come from the server environment.
Process isolation: In local mode, keys stay in your personal machine's environment.
OAuth token encryption: OAuth mode uses AES-256-GCM with MCP_TOKEN_SECRET. Access tokens last one hour; refresh tokens last 30 days and rotate when used. Replay and revocation state is held in process memory.
Client safety confirmations: MCP clients (like Claude and Gemini CLI) prompt you before executing actions.

For complete details, please read our Security Policy.

⚙️ Environment Variables & Options

Command-Line Flags

Flag	Description	Default
`--read-write`	Enables tools that modify store data	`false` (Read-only)
`--http`	Starts the remote Streamable HTTP server instead of stdio	`false`
`--port <number>`	HTTP port to listen on	`3000` (or `$PORT`)
`--host <string>`	HTTP host to bind	`0.0.0.0` (or `$HOST`)
`--public-url <url>`	Public HTTPS endpoint ending in `/mcp` for OAuth discovery	`http://localhost:<port>/mcp`
`-v, --version`	Display version number
`-h, --help`	Display help screen

Environment Variables

Variable	Applies to	Purpose
`AUTHMODE`	HTTP	`oauth`, `insecure-env`, or `secure-sqlite`; inferred as described above when unset
`SQUARESPACE_API_KEY`	Stdio and API-key HTTP modes	Outbound Squarespace credential; not used for OAuth-mode callers
`SQUARESPACE_ACCESS_TOKEN`	Stdio and API-key HTTP modes	Alternative outbound credential; required for webhook operations
`SQUARESPACE_MCP_READ_ONLY`	Both transports	Defaults to `true`; set `false` to expose write tools
`MCP_PUBLIC_URL`	HTTP	Exact public HTTPS endpoint ending in `/mcp`
`MCP_TOKEN_SECRET`	OAuth HTTP	Required; random 32+ character secret for encrypted OAuth tokens
`MCPAPIKEY`	`insecure-env` HTTP	Required inbound MCP bearer key
`SQLITEDBPATH`	`secure-sqlite` HTTP	Defaults to `/data/squarespace-mcp.sqlite`; requires persistent storage
`INITAPIKEY`	`secure-sqlite` HTTP	Required on first boot; initial inbound admin key
`MASTERENCRYPTIONKEY`	`OAuthSessionStore` helper	32+ character root key for encrypted stored sessions; the HTTP routes do not use this helper
`PORT`	HTTP	Defaults to `3000`

🛠️ Development & Contributing

Contributions and feedback are very welcome!

Local Development Setup

# Clone the repository
git clone https://github.com/FloraSync/squarespace-mcp.git
cd squarespace-mcp

# Install dependencies
npm ci

# Run quality checks
npm run typecheck       # TypeScript verification
npm run lint            # ESLint
npm run format:check    # Prettier style check
npm test                # Vitest test suite
npm run test:coverage   # Full coverage report
npm run build           # Compile to dist/

Keeping in Sync with Squarespace

When Squarespace updates their official Commerce API schema:

# Automatically fetches the latest official OpenAPI schema and regenerates tool definitions
npm run sync:api
npm test

🏷️ Releases

Releases are published automatically to npm with cryptographic provenance upon tagging:

git tag v0.1.0
git push origin v0.1.0

Prebuilt multi-arch Docker images are published to GitHub Container Registry:

docker pull ghcr.io/florasync/squarespace-mcp:0.1.0

📚 Resources & Links

📜 License & Legal

Distributed under the MIT License. See LICENSE for more information.

Disclaimer: Squarespace is a registered trademark of Squarespace, Inc. Gemini is a trademark of Google LLC. This open-source project is independently maintained by FloraSync and is not officially affiliated with or endorsed by Squarespace or Google.

Name		Name	Last commit message	Last commit date
.github		.github
docs		docs
scripts		scripts
src		src
test		test
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
.prettierignore		.prettierignore
.prettierrc.json		.prettierrc.json
CHANGELOG.md		CHANGELOG.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
eslint.config.js		eslint.config.js
package-lock.json		package-lock.json
package.json		package.json
server.json		server.json
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Navigation Menu

Repository files navigation

🛍️ Squarespace MCP

✨ What can you ask your AI?

🚀 Quick Start (Choose Your Setup)

🔑 Step 1: Get Your Squarespace API Key

💻 Local Desktop Setup (Claude, Cursor, Gemini CLI)

🟣 Claude Desktop

🔵 Gemini CLI / Antigravity CLI

🟢 Cursor & IDE Setup

⚡ Quick Command-Line Test

🌐 Gemini Spark (Web App)

How to connect Gemini Spark:

HTTP Authentication Modes

✍️ Enabling Write Mode (Optional)

🧰 What It Supports (52 Operations)

🔒 Security & Privacy

⚙️ Environment Variables & Options

Command-Line Flags

Environment Variables

🛠️ Development & Contributing

Local Development Setup

Keeping in Sync with Squarespace

🏷️ Releases

📚 Resources & Links

📜 License & Legal

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

🛍️ Squarespace MCP

✨ What can you ask your AI?

🚀 Quick Start (Choose Your Setup)

🔑 Step 1: Get Your Squarespace API Key

💻 Local Desktop Setup (Claude, Cursor, Gemini CLI)

🟣 Claude Desktop

🔵 Gemini CLI / Antigravity CLI

🟢 Cursor & IDE Setup

⚡ Quick Command-Line Test

🌐 Gemini Spark (Web App)

How to connect Gemini Spark:

HTTP Authentication Modes

✍️ Enabling Write Mode (Optional)

🧰 What It Supports (52 Operations)

🔒 Security & Privacy

⚙️ Environment Variables & Options

Command-Line Flags

Environment Variables

🛠️ Development & Contributing

Local Development Setup

Keeping in Sync with Squarespace

🏷️ Releases

📚 Resources & Links

📜 License & Legal

About

Topics

Resources

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages