A comprehensive Model Context Protocol (MCP) server for Squarespace, providing complete integration with the Squarespace platform for website management, e-commerce operations, content creation, and analytics.

Overview

This MCP server enables AI assistants to interact with Squarespace sites through a rich set of 67 tools covering all major platform features. Built with TypeScript and the official MCP SDK, it provides type-safe, reliable access to Squarespace's v1.0 API with OAuth2 authentication, automatic token refresh, pagination, error handling, and retry logic.

Features

🛍️ Complete API Coverage (67 Tools)

Commerce - Orders (8 tools)

List, search, and filter orders by date range, status, email
Get detailed order information with line items and fulfillment
Create orders (for importing from external sources)
Fulfill orders with optional shipping notifications and tracking
Add internal notes to orders
Get pending orders and recent orders

Commerce - Products (10 tools)

List all products with pagination
Get detailed product information with variants and images
Create new products with variants
Update products (name, description, pricing, SEO)
Delete products
Create, update, and delete product variants
Search products by name or tag
Filter products by tags

Commerce - Inventory (5 tools)

Get inventory levels for variants
Update inventory quantities
Adjust inventory by relative amounts
Check for low stock items (configurable threshold)
List out-of-stock items

Commerce - Transactions (3 tools)

Get all transactions for an order
Process refunds
Get transaction summaries (total paid, refunded, net)

Profiles (7 tools)

List all profiles (customers, subscribers, donors)
Get detailed profile information
List customers with purchase history
List mailing list subscribers
List donors
Search profiles by email
Get top customers by lifetime value

Webhooks (7 tools)

List all webhook subscriptions
Get webhook details
Create new webhooks for events (order.create, inventory.update, etc.)
Update webhook configurations
Delete webhooks
Send test notifications
Rotate webhook secrets for security

Pages & Website (8 tools)

Get website information
List and get collections
List, get, create, update, and delete pages
Manage page SEO settings

Forms (5 tools)

List all forms
Get form details with fields
List form submissions with filtering
Get specific submission details
Export form submissions as CSV

Blog (9 tools)

List all blog collections
Get blog details
List blog posts with pagination
Get specific blog post
Create new blog posts
Update blog posts
Delete blog posts
Publish and unpublish posts

Analytics (5 tools)

Get revenue metrics (total revenue, order count, AOV)
Get top-selling products by revenue
Get daily sales breakdowns
Get monthly revenue summary
Get yearly revenue summary

🎨 15 React MCP Apps (Dark Theme)

All apps are standalone Vite-based React applications with dark theme:

Orders Dashboard - Order management and fulfillment
Products Manager - Product catalog management
Inventory Tracker - Real-time inventory monitoring
Customer Profiles - Customer LTV and history
Analytics Dashboard - Revenue and sales insights
Blog Editor - Blog post management
Forms Viewer - Form submissions and export
Webhook Manager - Webhook configuration and testing
Page Manager - Website page management
Bulk Editor - Bulk product updates
SEO Optimizer - SEO settings and optimization
Reports - Generate and download reports
Shipping Manager - Fulfillment tracking
Discount Manager - Discount code management
Settings - Server and API configuration

🔒 Enterprise-Grade Features

OAuth2 Authentication - Full OAuth2 support with refresh tokens
Automatic Token Refresh - Seamless token renewal before expiration
Retry Logic - Automatic retry with exponential backoff for rate limits and errors
Pagination Support - Handle large datasets efficiently
Error Handling - Comprehensive error messages with details
Type Safety - Full TypeScript types for all API entities
Rate Limit Management - Built-in rate limit handling

Installation

npm install @mcpengine/squarespace-server

Or install from source:

cd servers/squarespace
npm install
npm run build

Configuration

Environment Variables

The server requires at minimum a Squarespace access token:

export SQUARESPACE_ACCESS_TOKEN="your_access_token_here"

For long-term access with automatic token refresh:

export SQUARESPACE_ACCESS_TOKEN="your_access_token"
export SQUARESPACE_REFRESH_TOKEN="your_refresh_token"
export SQUARESPACE_CLIENT_ID="your_client_id"
export SQUARESPACE_CLIENT_SECRET="your_client_secret"

MCP Configuration

Add to your MCP settings file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "squarespace": {
      "command": "squarespace-mcp",
      "env": {
        "SQUARESPACE_ACCESS_TOKEN": "your_access_token",
        "SQUARESPACE_REFRESH_TOKEN": "your_refresh_token",
        "SQUARESPACE_CLIENT_ID": "your_client_id",
        "SQUARESPACE_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

Getting Squarespace API Credentials

1. Register Your OAuth Application

Submit a request to Squarespace to register your OAuth application:

Squarespace Developer Portal
Provide: App name, icon, redirect URI, terms & privacy links

You'll receive:

client_id
client_secret

2. OAuth Flow

Implement the OAuth2 authorization code flow:

Authorization URL:

https://login.squarespace.com/api/1/login/oauth/provider/authorize?
  client_id=YOUR_CLIENT_ID&
  redirect_uri=YOUR_REDIRECT_URI&
  scope=website.orders,website.products,website.inventory&
  state=RANDOM_STATE&
  access_type=offline

Token Exchange:

curl -X POST https://login.squarespace.com/api/1/login/oauth/provider/tokens \
  -H "Authorization: Basic BASE64(client_id:client_secret)" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "code": "AUTHORIZATION_CODE",
    "redirect_uri": "YOUR_REDIRECT_URI"
  }'

API Scopes

Request these scopes for full functionality:

website.orders - Read and manage orders
website.orders.read - Read-only order access
website.products - Manage products
website.products.read - Read-only product access
website.inventory - Manage inventory
website.inventory.read - Read-only inventory access
website.transactions.read - Read transaction data

Usage Examples

List Recent Orders

{
  "name": "squarespace_list_orders",
  "arguments": {
    "modifiedAfter": "2024-01-01T00:00:00Z",
    "fulfillmentStatus": "PENDING"
  }
}

Create a Product

{
  "name": "squarespace_create_product",
  "arguments": {
    "product": {
      "type": "PHYSICAL",
      "storePageId": "store_page_id",
      "name": "New Product",
      "description": "Product description",
      "variants": [{
        "sku": "SKU-001",
        "pricing": {
          "basePrice": {
            "value": "29.99",
            "currency": "USD"
          }
        },
        "stock": {
          "quantity": 100,
          "unlimited": false
        }
      }]
    }
  }
}

Fulfill an Order

{
  "name": "squarespace_fulfill_order",
  "arguments": {
    "orderId": "order_id_here",
    "shouldSendNotification": true,
    "shipments": [{
      "carrierName": "USPS",
      "trackingNumber": "1234567890",
      "trackingUrl": "https://tools.usps.com/go/TrackConfirmAction?tLabels=1234567890"
    }]
  }
}

Get Revenue Analytics

{
  "name": "squarespace_get_revenue_metrics",
  "arguments": {
    "startDate": "2024-01-01T00:00:00Z",
    "endDate": "2024-01-31T23:59:59Z"
  }
}

Check Low Stock Items

{
  "name": "squarespace_check_low_stock",
  "arguments": {
    "threshold": 10
  }
}

Architecture

squarespace/
├── src/
│   ├── clients/
│   │   └── squarespace.ts       # API client with auth & retry logic
│   ├── types/
│   │   └── index.ts             # Complete TypeScript types
│   ├── tools/
│   │   ├── commerce-orders.ts   # Order management tools
│   │   ├── commerce-products.ts # Product management tools
│   │   ├── commerce-inventory.ts# Inventory management tools
│   │   ├── commerce-transactions.ts # Transaction tools
│   │   ├── profiles.ts          # Customer/subscriber tools
│   │   ├── webhooks.ts          # Webhook management tools
│   │   ├── pages.ts             # Page management tools
│   │   ├── forms.ts             # Form submission tools
│   │   ├── blog.ts              # Blog management tools
│   │   └── analytics.ts         # Analytics tools
│   ├── ui/
│   │   └── react-app/          # 15 React MCP apps
│   ├── server.ts                # MCP server implementation
│   └── main.ts                  # Entry point
├── package.json
├── tsconfig.json
└── README.md

API Reference

Full documentation: Squarespace Developer Docs

Rate Limits

Squarespace enforces varying rate limits per endpoint with 1-minute cooldowns. The client automatically handles rate limiting with retry logic.

Webhooks

Subscribe to real-time events:

order.create - New order created
order.update - Order updated
transaction.create - New transaction
transaction.update - Transaction updated
inventory.update - Inventory changed
product.create - Product created
product.update - Product updated
product.delete - Product deleted

Development

Build

npm run build

Type Check

npm run type-check

Development Mode

npm run dev

Troubleshooting

Authentication Errors

401 Unauthorized: Token expired or invalid - refresh your token
403 Forbidden: Insufficient scopes - request additional permissions
Token refresh fails: Verify client credentials are correct

Rate Limiting

429 Too Many Requests: Built-in retry handles this automatically
Implement delays between bulk operations for best performance

Common Issues

Missing environment variables: Ensure SQUARESPACE_ACCESS_TOKEN is set
TypeScript errors: Run npm run type-check to diagnose
Module resolution: Verify package.json has "type": "module"

Contributing

Contributions welcome! Please:

Follow existing code structure
Add tests for new tools
Update documentation
Run type checking before submitting

License

MIT License - see LICENSE file for details

Support

Changelog

v1.0.0 (2024-02-12)

Initial release
67 tools covering all major Squarespace features
15 React MCP apps with dark theme
OAuth2 authentication with auto-refresh
Comprehensive error handling and retry logic
Full TypeScript support