Skip to main content
Glama
squarespace-mcp

squarespace-mcp

by The1Studio

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

Related MCP server: MCP Shopify Admin Server

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.

Available Tools

11 tools
adjust_inventoryA

MUTATES THE LIVE STORE. Set a variant's stock to an exact quantity.

This overwrites the current stock level for variant_id with the given finite quantity (a "set" operation, not a delta). Sent with an idempotency key. Returns the API result; a 204 is normalised to {}. Use only when you intend to change real inventory.

Inputs: quantity (required), variant_id (required). Returns: object

fulfill_orderA

MUTATES THE LIVE STORE. Mark an order fulfilled with shipment details.

shipments is a list of shipment objects, each accepting carrierName, service, shipDate (ISO-8601), trackingNumber, and trackingUrl. When should_send_notification is true (default), Squarespace emails the customer. Use only when actually shipping an order.

Inputs: order_id (required), shipments (required), should_send_notification. Returns: object

get_inventoryA

Retrieve inventory for specific variants (up to 50 ids per call).

Use when you know exact variant ids and want their current stock.

Inputs: variant_ids (required). Returns: object

get_orderA

Retrieve a single order by its id, including line items and totals.

Inputs: order_id (required). Returns: object

get_productA

Retrieve product(s) by id (Products v2).

Accepts a single id, or a comma-separated list of up to 50 ids to fetch several at once. Use when you already know the id(s).

Inputs: product_id (required). Returns: object

get_profileA

Retrieve a single customer profile by its id.

Inputs: profile_id (required). Returns: object

list_inventoryA

List inventory items (stock levels) across variants, 50 per page.

Use to audit stock. Page forward with cursor from the prior response.

Inputs: cursor. Returns: object

list_ordersA

List store orders (up to 50 per page, newest-modified first).

Filter with fulfillment_status (PENDING, FULFILLED, or CANCELED) and/or modified_after (ISO-8601 UTC). Page with cursor.

Inputs: cursor, modified_after, fulfillment_status. Returns: object

list_productsA

List store products (Products v2; up to 50 per page).

Use to browse the catalog. Filter with modified_after / modified_before (ISO-8601 UTC, e.g. 2024-01-01T00:00:00Z), type (PHYSICAL | SERVICE | GIFT_CARD | DIGITAL), or query (free-text search). Page forward with cursor from the previous response's pagination.nextPageCursor — send cursor ALONE, it cannot be combined with the filters.

Inputs: type, query, cursor, modified_after, +1 more. Returns: object

list_profilesA

List customer profiles (contacts/customers), 50 per page.

Page forward with cursor from the prior response.

Inputs: cursor. Returns: object

list_transactionsA

List financial transactions for orders and donations (50 per page).

Bound the window with modified_after / modified_before (ISO-8601 UTC) and page with cursor.

Inputs: cursor, modified_after, modified_before. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 11 tools

    Disambiguation5/5

    Each tool has a clear, distinct purpose. The list/get pairs (e.g., list_products vs get_product) are differentiated by whether you're browsing with filters or fetching known IDs, and the two mutations (adjust_inventory, fulfill_order) are unambiguous.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case: list_* and get_* for reads, adjust_inventory and fulfill_order for writes. The naming is predictable and easy to navigate.

    Tool Count5/5

    At 11 tools, the server is well-scoped for an e-commerce operations context. It covers the major resources (transactions, products, inventory, orders, profiles) without unnecessary duplication or bloat.

    Completeness3/5

    The read surface is strong with list/get for all core resources, and the mutations cover inventory adjustment and order fulfillment. However, there are notable gaps: no create/update/delete for products or orders, no order cancellation, and no profile management operations.

    Related MCP Connectors

    Related MCP Servers