squarespace-mcp

An MCP server that exposes the Squarespace Commerce API as tools an LLM agent can call — read products, inventory, orders, transactions, and customer profiles, and (with care) adjust inventory and fulfill orders.

• Stack: Python + FastMCP 2.x/3.x
• Transport: stdio
• API: Squarespace Commerce APIs (https://api.squarespace.com), Bearer-key auth

Setup

# with uv (recommended)
uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"

# or plain pip
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

cp .env.example .env   # then fill in SQUARESPACE_API_KEY

Get an API key from Squarespace → Settings → Developer API keys. The key is read from the environment (or a local .env) lazily — the server starts and registers its tools even with no key set; a clear error is raised only when a tool is actually invoked without one.

Environment variables

Variable	Required	Default	Purpose
SQUARESPACE_API_KEY	yes (at call time)	—	Bearer API key
SQUARESPACE_API_VERSION	no	1.0	Version for inventory / orders / transactions / profiles
SQUARESPACE_PRODUCTS_API_VERSION	no	v2	Products is versioned independently — v2 is current (legacy 1.0/1.1 not for new integrations)
SQUARESPACE_USER_AGENT	no	squarespace-mcp/0.1 …	Squarespace requires a descriptive User-Agent

Run

squarespace-mcp            # runs the MCP server over stdio

The process reads/writes MCP frames on stdin/stdout and blocks waiting for a client — that is expected. It is meant to be launched by an MCP client, not run interactively.

Register with Claude Code

claude mcp add squarespace \
  --env SQUARESPACE_API_KEY=your_key_here \
  -- /absolute/path/to/squarespace-mcp/.venv/bin/squarespace-mcp

(Or point the command at uv run squarespace-mcp / your installed console script.) After registering, the tools below appear to the agent.

Tools

Read (safe)

Tool	Purpose
list_products(cursor?, modified_after?)	List catalog products, 50/page
get_product(product_id)	Retrieve one product
list_inventory(cursor?)	List stock levels, 50/page
get_inventory(variant_ids)	Stock for specific variants (≤50 ids)
list_orders(cursor?, modified_after?, fulfillment_status?)	List orders (filter PENDING/FULFILLED/CANCELED)
get_order(order_id)	Retrieve one order
list_transactions(cursor?, modified_after?, modified_before?)	List financial transactions
list_profiles(cursor?)	List customer profiles
get_profile(profile_id)	Retrieve one profile

Pagination: list tools return the raw Squarespace page including a pagination object; pass its nextPageCursor back as cursor to page forward.

Write (⚠️ mutates the live store)

Tool	Purpose
adjust_inventory(variant_id, quantity)	Set a variant's stock to an exact quantity (sent with an idempotency key)
fulfill_order(order_id, shipments, should_send_notification=true)	Mark an order fulfilled with shipment details; optionally emails the customer

Destructive operations (product delete, etc.) are intentionally not implemented.

Development

pytest -q          # all HTTP is mocked with respx — no network calls

Security

• Real credentials live in .env (gitignored). Only .env.example is committed.
• Never hardcode the API key; it is read from the environment at runtime.
• The client raises on any non-2xx response (status + body) — no silent fallbacks.