Shopify-Checkout-Branding-MCP-Tool

shandut/Shopify-Checkout-Branding-MCP-Tool

3.2

If you are the rightful owner of Shopify-Checkout-Branding-MCP-Tool and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

A Model Context Protocol (MCP) server for comprehensive Shopify checkout branding management through AI-powered tools.

Tools
4
Resources
0
Prompts
0

Shopify Checkout Branding MCP Tool

A Model Context Protocol (MCP) server for comprehensive Shopify checkout branding management through AI-powered tools. This production-ready server enables AI assistants like Claude and Cursor to programmatically customize every aspect of your Shopify Plus checkout - from colors and typography to sections, form controls, and complete design systems.

🚀 Production-Ready: Full API compatibility, intelligent value mapping, enhanced tool descriptions, and safety-first defaults for accurate AI-driven checkout customization.

✅ Cursor MCP Support Fixed!

The MCP server now works correctly with Cursor. The JSON communication issue has been resolved. See for details.

🎯 Quick Start

For Claude Desktop Users

  1. Install and configure:
# Clone and setup
git clone https://github.com/shandut/Shopify-Checkout-Branding-MCP-Tool.git
cd shopify-checkout-mcp-tool
npm install
npm run build

# Create .env file with your credentials
cp env.template .env
# Edit .env with your Shopify store details

  1. Configure Claude Desktop (see Configuration section below)

  2. Use natural language in Claude:

  • "Show me all checkout profiles"
  • "Center the logo and make it 150px wide"
  • "Change the primary color to #5A31F4"

For Cursor/HTTP API Users

  1. Start the HTTP server:
npm run start:http
  1. Test the API:
node test-http.js

🚀 Features

Core Tools

  • List Checkout Profiles: Retrieve all checkout profiles with TEST/PUBLISHED status
  • Read Current Branding: Get complete branding configuration and design system
  • Update Branding: Comprehensive customization with intelligent defaults
    • 🔒 Safety Feature: Automatically targets TEST/draft profile by default
    • Use useProductionProfile: true to explicitly update live checkout
  • Upload Logos: Stream images from URLs directly to Shopify CDN
  • Upload Custom Fonts: Upload WOFF/WOFF2/TTF/OTF fonts for unique typography

Styling Capabilities

  • Colors: Background, text, primary (buttons), surface colors with hex validation
  • Typography: Font families (Shopify or custom), weights (100-900), base size (12-16), ratios (1.0-1.5)
    • Custom font support for primary (body text) and secondary (headings) surfaces
    • Configurable font loading strategies (BLOCK, SWAP, FALLBACK, OPTIONAL)
  • Corner Radius: NONE, SMALL, BASE, LARGE for all elements
  • Shadows: 5 levels (SMALL_100, SMALL_200, BASE, LARGE_100, LARGE_200)
  • Padding: 14 variants (NONE through LARGE_500)
  • Sections: Independent main area and order summary styling with dividers
  • Form Controls: Borders, labels (INSIDE/OUTSIDE), corner radius
  • Color Schemes: 4 schemes for different section contexts
  • Header: Logo visibility, banner images, cart links, alignment, dividers
  • Background Images: Support for header banner, main area, order summary
  • Container Dividers: Configurable style (BASE/DASHED/DOTTED), width, visibility
  • Cart Link: Custom content type (ICON/IMAGE/TEXT) with image support

API Intelligence

  • Multi-version Support: Compatible with API versions 2024-10 through 2026-01
  • Value Mapping: Automatic conversion for API compatibility
  • Enhanced Descriptions: Detailed tool documentation for better AI understanding
  • Error Recovery: Intelligent handling of validation errors

📋 Prerequisites

  • Node.js 18+ with TypeScript support
  • Shopify store with Admin API access
  • Shopify Admin API token with appropriate scopes:
    • read_checkout_branding_settings
    • write_checkout_branding_settings
    • write_files (for logo uploads)

🛠️ Installation

⚠️ Security Note

Never commit your actual API credentials to version control!

  • Copy env.template to .env for your credentials
  • .env is already in .gitignore to prevent accidental commits
  • All example configurations use placeholder values

Setup Steps

  1. Clone the repository:
git clone https://github.com/shandut/Shopify-Checkout-Branding-MCP-Tool.git
cd shopify-checkout-mcp-tool
  1. Install dependencies:
npm install
  1. Build the project:
npm run build
  1. Configure environment variables:
cp env.template .env

Edit .env with your Shopify credentials:

SHOPIFY_STORE_DOMAIN=your-store.myshopify.com
SHOPIFY_ADMIN_TOKEN=shpat_your_admin_api_token_here
SHOPIFY_API_VERSION=2026-01
PORT=8787  # Only if using HTTP wrapper

🔧 Configuration

For Claude Desktop

Add to your Claude Desktop configuration file:

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

{
  "mcpServers": {
    "shopify-checkout": {
      "command": "node",
      "args": ["/path/to/shopify-checkout-mcp-tool/dist/index.js"],
      "env": {
        "SHOPIFY_STORE_DOMAIN": "your-store.myshopify.com",
        "SHOPIFY_ADMIN_TOKEN": "shpat_your_admin_api_token_here",
        "SHOPIFY_API_VERSION": "2026-01"
      }
    }
  }
}

For Cursor or Other Tools (HTTP Mode)

Run with HTTP wrapper enabled:

npm run start:http

The server will be available at http://localhost:8787

📚 Available MCP Tools

1. shopify_list_checkout_profiles

Lists all checkout profiles in your store.

Input: None required Output: Array of profiles with id, name, and status

2. shopify_get_checkout_branding

Retrieves current branding settings for a specific profile.

Input:

  • profileId (string): Shopify GID of the checkout profile

Output: Current logo configuration and color scheme

3. shopify_update_checkout_branding

Updates branding settings for a checkout profile. 🔒 Defaults to TEST profile for safety.

Input:

  • profileId (string, optional): Shopify GID - if not provided, auto-selects TEST profile
  • useProductionProfile (boolean, optional): Set to true to update live checkout (default: false)
  • logoWidth (number, optional): Width in pixels (1-1000)
  • logoPosition (enum, optional): "LEFT", "CENTER", or "RIGHT"
  • colors (object, optional):
    • background: Hex color (e.g., "#FFFFFF")
    • surface: Hex color
    • text: Hex color
    • primary: Hex color for buttons
    • primaryText: Hex color for button text
  • control (object, optional): Form control styling
    • color: "TRANSPARENT"
    • border: "NONE" or "FULL"
    • cornerRadius: Corner style
    • labelPosition: "INSIDE" or "OUTSIDE"
  • imageId (string, optional): ID of uploaded logo

4. shopify_upload_logo_from_url

Uploads an image from a URL to Shopify Files.

Input:

  • url (string, required): Public HTTPS URL of the image
  • filename (string, optional): Desired filename
  • mimeType (string, optional): Image MIME type

Output: Image ID and CDN URL for use in branding updates

5. shopify_upload_custom_font_from_url

Uploads a custom font file from a URL to Shopify Files for use in checkout typography.

Input:

  • url (string, required): Public HTTPS URL of the font file (WOFF, WOFF2, TTF, or OTF)
  • filename (string, optional): Desired filename for the font
  • mimeType (string, optional): Font MIME type (auto-detected if not provided)
  • fontWeight (number, optional): Font weight (100-900, default 400 for regular, 700 for bold)
  • isBold (boolean, optional): Mark as bold variant (sets weight to 700)

Output:

  • genericFileId: File ID to use in checkout branding configuration
  • url: CDN URL of the uploaded font
  • weight: Font weight value
  • filename: The filename of the uploaded font

💡 Usage Examples

Via MCP (in Claude Desktop)

After configuring Claude Desktop, you can use natural language:

"Can you reduce my checkout logo width by half and center it?"

Claude will:

  1. Call shopify_get_checkout_branding to get current width
  2. Calculate new width (50% of current)
  3. Call shopify_update_checkout_branding with new settings
  4. Verify changes with another shopify_get_checkout_branding call

Via HTTP API (for Cursor)

# List all checkout profiles
curl http://localhost:8787/profiles

# Get current branding
curl http://localhost:8787/profiles/gid://shopify/CheckoutProfile/123/branding

# Update branding (safer - auto-targets TEST profile)
curl -X POST http://localhost:8787/branding \
  -H "Content-Type: application/json" \
  -d '{
    "logoWidth": 150,
    "logoPosition": "CENTER",
    "colors": {
      "primary": "#5A31F4",
      "background": "#FFFFFF"
    }
  }'

# Update production checkout (explicit)
curl -X POST http://localhost:8787/branding \
  -H "Content-Type: application/json" \
  -d '{
    "useProductionProfile": true,
    "logoWidth": 150,
    "colors": {
      "primary": "#5A31F4"
    }
  }'

# Upload new logo
curl -X POST http://localhost:8787/files \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/new-logo.png",
    "filename": "checkout-logo.png"
  }'

# Upload custom fonts
curl -X POST http://localhost:8787/fonts \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/myfont-regular.woff2",
    "fontWeight": 400
  }'

# Apply custom font to checkout
curl -X POST http://localhost:8787/branding \
  -H "Content-Type: application/json" \
  -d '{
    "designSystem": {
      "typography": {
        "primary": {
          "customFontGroup": {
            "base": {
              "genericFileId": "gid://shopify/GenericFile/123456",
              "weight": 400
            },
            "bold": {
              "genericFileId": "gid://shopify/GenericFile/789012",
              "weight": 700
            },
            "loadingStrategy": "SWAP"
          }
        }
      }
    }
  }'

🏗️ Architecture

src/
├── index.ts           # Application entry point
├── mcpServer.ts       # MCP server implementation
├── httpServer.ts      # Optional Fastify HTTP wrapper
├── shopify.ts         # GraphQL client for Shopify API
├── branding.ts        # Business logic for branding operations
├── schemas.ts         # Zod schemas for validation
└── logging.ts         # Pino logger with security redaction

🔐 Security

  • Token Protection: API tokens are never logged or exposed in responses
  • Input Validation: All inputs validated using Zod schemas
  • Rate Limiting: Automatic retry with exponential backoff for Shopify API limits
  • HTTPS Only: Only accepts HTTPS URLs for image uploads
  • Scoped Permissions: Limited to checkout branding and file operations

🧪 Testing

Run tests:

npm test

Test against a development store:

npm run test:integration

📝 Development

Start development server with hot reload:

npm run dev

Build for production:

npm run build

Start production server:

npm start

🚦 Error Handling

The server handles various error scenarios:

  • 400: Invalid input or validation errors
  • 403: Missing required Shopify API scopes
  • 429: Rate limited (automatic retry with backoff)
  • 500: Unexpected server errors

🤝 Contributing

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

⚠️ Known Limitations & Important Notes

Typography Field Restrictions

The customizations.global.typography field has strict limitations:

  • ✅ Allowed: kerning (BASE, LOOSE, EXTRA_LOOSE), letterCase (NONE, LOWER, TITLE, UPPER)
  • ❌ NOT Allowed: font, size, weight (use designSystem.typography for these)

Other API Limitations

  • Global Corner Radius: Only accepts NONE value
  • Control Color: Only accepts TRANSPARENT value
  • Logo Format: SVG files cannot be used for checkout logos
  • Enum Values: Some enum values differ between API versions (e.g., UPPER vs UPPERCASE)

🆘 Support

For issues, questions, or suggestions:

  • Open an issue on GitHub
  • Check existing issues for solutions
  • Review Shopify Admin API documentation

🗺️ Roadmap

  • Support for multiple store configurations
  • Bulk profile updates
  • Preview generation before applying changes
  • Backup and restore functionality
  • WebSocket support for real-time updates
  • Integration with Shopify webhooks
  • Support for theme-based branding
  • A/B testing capabilities