Swell MCP

Swell MCP Server

A Model Context Protocol server that integrates AI assistants with Swell's e-commerce platform. Built on a production-ready TypeScript foundation, it provides comprehensive access to Swell stores for product management, order processing, and customer management through both CLI and MCP tool interfaces.

Built by [Devkind](https://devkind.com.au/services/swell) - Official Swell Partners serving businesses globally with cutting-edge e-commerce solutions.

Features

• Swell E-commerce Integration: Complete access to Swell's API for products, orders, and customers
• Dual Transport Support: STDIO and HTTP transports for AI assistant and web integration
• 5-Layer Architecture: Clean separation between CLI, tools, controllers, services, and utilities
• Type Safety: Full TypeScript implementation with Zod schema validation
• Advanced HTTP Client: Built on swell-node SDK with connection pooling and retry logic
• Comprehensive Testing: Unit and integration tests with Swell API mocking
• Production Tooling: ESLint, Prettier, semantic-release, and MCP Inspector integration
• Error Handling: Structured error handling with Swell-specific error contexts

Swell E-commerce Integration

This MCP server provides comprehensive integration with Swell's e-commerce platform:

Available Tools & Commands

MCP Tools:

• swell_list_products - List products with filtering and pagination
• swell_get_product - Get detailed product information
• swell_search_products - Search products with multiple criteria
• swell_check_inventory - Check product inventory levels
• swell_list_orders - List orders with filtering options
• swell_get_order - Get detailed order information
• swell_update_order_status - Update order status
• swell_list_customers - List customers with search capabilities
• swell_get_customer - Get detailed customer information
• swell_search_customers - Search customers with multiple criteria

Features Demonstrated

• Product Management: Complete product catalog access with inventory tracking
• Order Processing: Order lifecycle management with status updates
• Customer Management: Customer profiles with order history and analytics
• Error Handling: Structured errors for API failures and validation issues
• Response Formatting: Clean Markdown output with structured data tables

Configuration Requirements

# Required - Swell API credentials

SWELL_STORE_ID=your-store-id SWELL_SECRET_KEY=your-secret-key

Development

DEBUG=true # Enable detailed logging TRANSPORT_MODE=http # Use HTTP transport PORT=3001 # Custom port

Need Advanced Swell Checkout?

This MCP server demonstrates the kind of sophisticated Swell integrations that power [CheckoutJet](https://checkoutjet.com/) - an enterprise-grade checkout solution for Swell stores built by Devkind.

CheckoutJet transforms your Swell checkout with:

• 🏢 B2B Excellence - Professional invoicing, Net 30 payments, and wholesale pricing
• 📦 Smart Shipping - Live rates from multiple locations with intelligent order routing
• ⚡ Split Deliveries - Handle complex multi-vendor and multi-warehouse fulfillment
• 🎨 Full Customization - Pixel-perfect, on-brand checkout experience
• 🤖 Automation - Automated invoicing, POs, and order management
• 💰 Advanced Pricing - Dynamic discounts and tiered pricing logic

Proven Results: Over €500,000 processed for Swell merchants with 23% conversion rate improvements.

Ready to upgrade your Swell checkout? Book a 15-minute demo

What is MCP?

Model Context Protocol (MCP) is an open standard for securely connecting AI systems to external tools and data sources. This server implements the MCP specification to provide AI assistants with comprehensive access to Swell's e-commerce platform, enabling intelligent store management and customer service automation.

Getting Started

First, install the Swell MCP server with your AI assistant or MCP client.

Requirements

• Node.js 18 or newer
• VS Code, Cursor, Windsurf, Claude Desktop, or any other MCP client
• Swell store credentials (Store ID and Secret Key)

Standard config works in most MCP clients:

{

"mcpServers": { "swell-mcp": { "command": "npx", "args": ["swell-mcp"], "env": { "DEBUG": "false", "SWELL_STORE_ID": "your_store_id", "SWELL_SECRET_KEY": "your_private_token" }, "disabled": false } } }

Claude Desktop

Follow the MCP install guide, use the standard config above.

Add to your claude_desktop_config.json:

{

"mcpServers": { "swell-mcp": { "command": "npx", "args": ["swell-mcp"], "env": { "SWELL_STORE_ID": "your_store_id", "SWELL_SECRET_KEY": "your_private_token" } } } }

Cursor

Click the button to install:

Or install manually:

Go to Cursor Settings -> MCP -> Add new MCP Server. Name it "Swell MCP", use command type with the command npx swell-mcp. Add your Swell credentials in the environment variables section.

VS Code

Follow the MCP install guide, use the standard config above. You can also install the Swell MCP server using the VS Code CLI:

# For VS Code

code --add-mcp '{"name":"swell-mcp","command":"npx","args":["swell-mcp"],"env":{"SWELL_STORE_ID":"your_store_id","SWELL_SECRET_KEY":"your_private_token"}}'

After installation, the Swell MCP server will be available for use with your GitHub Copilot agent in VS Code.

Windsurf

Follow Windsurf MCP documentation. Use the standard config above.

Add to your MCP configuration:

{

"mcpServers": { "swell-mcp": { "command": "npx", "args": ["swell-mcp"], "env": { "SWELL_STORE_ID": "your_store_id", "SWELL_SECRET_KEY": "your_private_token" } } } }

Goose

Go to Advanced settings -> Extensions -> Add custom extension. Name it "Swell MCP", use type STDIO, and set the command to npx swell-mcp. Add your Swell credentials as environment variables. Click "Add Extension".

LM Studio

Go to Program in the right sidebar -> Install -> Edit mcp.json. Use the standard config above with your Swell credentials.

Warp

Go to Settings -> AI -> Manage MCP Servers -> + Add to add an MCP Server. Use the standard config above.

Alternatively, use the slash command /add-mcp in the Warp prompt and paste the standard config from above.

Configuration

Getting Your Swell Credentials

1. Log into your Swell dashboard at login.swell.store
2. Navigate to Developer → API Keys
3. Copy your Store ID (this is your SWELL_STORE_ID)
4. Copy your Secret Key (this is your SWELL_SECRET_KEY - use the backend/admin key, not the public key)

Environment Variables

• SWELL_STORE_ID: Your Swell store identifier (required)
• SWELL_SECRET_KEY: Your Swell secret/private key (required)
• DEBUG: Set to "true" to enable debug mode with raw JSON responses (optional)

Example Configuration

{

"mcpServers": { "swell-mcp": { "command": "npx", "args": ["swell-mcp"], "env": { "DEBUG": "false", "SWELL_STORE_ID": "my-awesome-store", "SWELL_SECRET_KEY": "sk_live_abc123def456..." }, "disabled": false } } }

Usage

Once installed in your MCP client (see Getting Started above), you can use the Swell MCP tools directly through your AI assistant:

Example Interactions

"List my active products"

→ Uses swell_list_products with active=true

"Show me pending orders from this week" → Uses swell_list_orders with status=pending and date filtering

"Update customer John Doe's email to john@example.com" → Uses swell_update_customer to modify customer information

"Check inventory for product ID abc123" → Uses swell_check_inventory for stock levels

Debug Mode

Enable debug mode to see raw JSON responses instead of formatted output:

{

"env": { "DEBUG": "true", "SWELL_STORE_ID": "your_store_id", "SWELL_SECRET_KEY": "your_private_token" } }

Transport Modes

STDIO Transport

• JSON-RPC communication via stdin/stdout
• Used by Claude Desktop, Cursor AI, and other local AI assistants
• Run with: TRANSPORT_MODE=stdio node dist/index.js

Streamable HTTP Transport

• HTTP-based transport with Server-Sent Events (SSE)
• Supports multiple concurrent connections and web integrations
• Runs on port 3000 by default (configurable via PORT env var)
• MCP Endpoint: http://localhost:3000/mcp
• Health Check: http://localhost:3000/ → Returns server version
• Run with: TRANSPORT_MODE=http node dist/index.js

Architecture Overview

Project Structure (Click to expand)

src/

├── cli/ # Command-line interfaces │ └── index.ts # CLI entry point with Commander setup ├── controllers/ # Business logic orchestration │ ├── swell.products.controller.ts # Product management logic │ ├── swell.products.formatter.ts # Product response formatting │ ├── swell.orders.controller.ts # Order management logic │ ├── swell.orders.formatter.ts # Order response formatting │ ├── swell.customers.controller.ts # Customer management logic │ └── swell.customers.formatter.ts # Customer response formatting ├── services/ # External API interactions │ ├── swell.products.service.ts # Swell products API service │ ├── swell.products.types.ts # Product type definitions │ ├── swell.orders.service.ts # Swell orders API service │ ├── swell.orders.types.ts # Order type definitions │ ├── swell.customers.service.ts # Swell customers API service │ └── swell.customers.types.ts # Customer type definitions ├── tools/ # MCP tool definitions (AI interface) │ ├── swell.products.tool.ts # Product management tools │ ├── swell.orders.tool.ts # Order management tools │ └── swell.customers.tool.ts # Customer management tools ├── types/ # Global type definitions │ └── common.types.ts # Shared interfaces (ControllerResponse, etc.) ├── utils/ # Shared utilities │ ├── logger.util.ts # Contextual logging system │ ├── error.util.ts # MCP-specific error formatting │ ├── error-handler.util.ts # Error handling utilities │ ├── config.util.ts # Environment configuration │ ├── constants.util.ts # Version and package constants │ ├── formatter.util.ts # Markdown formatting │ ├── swell-client.util.ts # Swell SDK client wrapper │