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 - 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 - 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
		}
	}
}

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

# 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"}}'

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

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