Squarespace MCP Server

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:

1. Orders Dashboard - Order management and fulfillment
2. Products Manager - Product catalog management
3. Inventory Tracker - Real-time inventory monitoring
4. Customer Profiles - Customer LTV and history
5. Analytics Dashboard - Revenue and sales insights
6. Blog Editor - Blog post management
7. Forms Viewer - Form submissions and export
8. Webhook Manager - Webhook configuration and testing
9. Page Manager - Website page management
10. Bulk Editor - Bulk product updates
11. SEO Optimizer - SEO settings and optimization
12. Reports - Generate and download reports
13. Shipping Manager - Fulfillment tracking
14. Discount Manager - Discount code management
15. 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:

1. 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

2. 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

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

Contributing

Contributions welcome! Please:

1. Follow existing code structure
2. Add tests for new tools
3. Update documentation
4. Run type checking before submitting

License

MIT License - see LICENSE file for details

Support

• Squarespace API Documentation
• MCP Protocol Specification
• GitHub Issues

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