Skip to content

devkindhq/swell-mcp

BranchesTags

Repository files navigation

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.

NPM Version License: ISC Built by Devkind

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

Install in Cursor

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
β”‚   └── transport.util.ts   # HTTP transport utilities
└── index.ts                # Server entry point (dual transport)

5-Layer Architecture

The server follows a clean, layered architecture that promotes maintainability and clear separation of concerns:

1. CLI Layer (src/cli/)

  • Purpose: Command-line interfaces for direct tool usage and testing
  • Implementation: Commander-based argument parsing with contextual error handling
  • Example: list-products --active --category electronics
  • Pattern: Register commands β†’ Parse arguments β†’ Call controllers β†’ Handle errors

2. Tools Layer (src/tools/)

  • Purpose: MCP tool definitions that AI assistants can invoke
  • Implementation: Zod schema validation with structured responses
  • Example: swell_list_products tool with filtering and pagination options
  • Pattern: Define schema β†’ Validate args β†’ Call controller β†’ Format MCP response

3. Resources Layer (src/resources/)

  • Purpose: MCP resources providing contextual data accessible via URIs (planned feature)
  • Implementation: Resource handlers that respond to URI-based requests
  • Example: swell://products/123 resource providing product details
  • Pattern: Register URI patterns β†’ Parse requests β†’ Return formatted content

4. Controllers Layer (src/controllers/)

  • Purpose: Business logic orchestration with comprehensive error handling
  • Implementation: Options validation, fallback logic, response formatting
  • Example: Product management with inventory tracking, order processing with status updates
  • Pattern: Validate inputs β†’ Apply defaults β†’ Call services β†’ Format responses

5. Services Layer (src/services/)

  • Purpose: Direct external API interactions with minimal business logic
  • Implementation: HTTP transport utilities with structured error handling
  • Example: Swell API calls with authentication and data validation
  • Pattern: Build requests β†’ Make API calls β†’ Validate responses β†’ Return raw data

6. Utils Layer (src/utils/)

  • Purpose: Shared functionality across all layers
  • Key Components:
    • logger.util.ts: Contextual logging (file:method context)
    • error.util.ts: MCP-specific error formatting
    • transport.util.ts: HTTP/API utilities with retry logic
    • config.util.ts: Environment configuration management

Development Setup

For developers who want to contribute or modify the server:

Prerequisites

  • Node.js (>=18.x): Download
  • Git: For version control

Quick Start

# Clone the repository
git clone https://github.com/devkindhq/swell-mcp.git
cd swell-mcp

# Install dependencies
npm install

# Configure your Swell credentials
cp .env.example .env
# Edit .env and add your SWELL_STORE_ID and SWELL_SECRET_KEY

# Build the project
npm run build

# Run in different modes:

# 1. STDIO Transport - For AI assistant integration (Claude Desktop, Cursor)
npm run mcp:stdio

# 2. HTTP Transport - For web-based integrations
npm run mcp:http

# 3. Development with MCP Inspector
npm run mcp:inspect                         # Auto-opens browser with debugging UI

Development Scripts

# Build and Clean
npm run build               # Build TypeScript to dist/
npm run clean               # Remove dist/ and coverage/
npm run prepare             # Build + ensure executable permissions (for npm publish)

# CLI Testing (coming soon)
# npm run cli -- list-products --active                   # List active products
# npm run cli -- get-product <product-id>                 # Get product details
# npm run cli -- list-orders --status pending             # List pending orders

# MCP Server Modes
npm run mcp:stdio           # STDIO transport for AI assistants
npm run mcp:http            # HTTP transport on port 3000
npm run mcp:inspect         # HTTP + auto-open MCP Inspector

# Development with Debugging
npm run dev:stdio           # STDIO with MCP Inspector integration
npm run dev:http            # HTTP with debug logging enabled

# Testing
npm test                    # Run all tests (Jest)
npm run test:coverage       # Generate coverage report
npm run test:cli            # Run CLI-specific tests

# Code Quality
npm run lint                # ESLint with TypeScript rules
npm run format              # Prettier formatting
npm run update:deps         # Update dependencies

Environment Variables

Core Configuration

  • TRANSPORT_MODE: Transport mode (stdio | http, default: stdio)
  • PORT: HTTP server port (default: 3000)
  • DEBUG: Enable debug logging (true | false, default: false)

Swell API Configuration

  • SWELL_STORE_ID: Your Swell store ID (required)
  • SWELL_SECRET_KEY: Your Swell secret key (required)

Example .env File

# Basic configuration
TRANSPORT_MODE=http
PORT=3001
DEBUG=true

# Swell API credentials (required)
SWELL_STORE_ID=your-store-id
SWELL_SECRET_KEY=your-secret-key

Debugging Tools

  • MCP Inspector: Visual tool for testing your MCP tools

    • Run server with npm run mcp:inspect
    • Open the URL shown in terminal
    • Test your tools interactively

  • Debug Logging: Enable with DEBUG=true environment variable

Configuration (Click to expand)

Create ~/.mcp/configs.json:

{
	"swell-mcp": {
		"environments": {
			"DEBUG": "true",
			"TRANSPORT_MODE": "http",
			"PORT": "3000",
			"SWELL_STORE_ID": "your-store-id",
			"SWELL_SECRET_KEY": "your-secret-key"
		}
	}
}

Available Tools

The Swell MCP server provides comprehensive e-commerce management tools for AI assistants. The list below matches the tool names and parameter schemas implemented under src/tools/.

Product Management

  • swell_list_products

    • Description: List products with filtering and pagination
    • Parameters: page, limit, active, category, tags, sort, expand

  • swell_get_product

    • Description: Get detailed product information
    • Parameters: productId, expand

  • swell_search_products

    • Description: Search products with text queries and optional filters
    • Parameters: query, page, limit, active, category, tags, sort, expand

  • swell_check_stock

    • Description: Check current stock levels and stock status for a product
    • Parameters: productId, includeVariants (default: true)

  • swell_update_product

    • Description: Update product metadata and attributes (name, description, SEO, tags, categories, attributes, active, sku, etc.)
    • Parameters: productId plus any editable product fields

  • swell_update_product_stock

    • Description: Adjust stock levels or update stock tracking settings
    • Parameters: productId, quantity, reason, reasonMessage, variantId, orderId

  • swell_update_product_pricing

    • Description: Update product pricing (regular price, sale price, currency)
    • Parameters: productId, price, salePrice, currency
Order Management

  • swell_list_orders

    • Description: List orders with filtering options
    • Parameters: page, limit, status, customerId, dateFrom, dateTo, sort, expand

  • swell_get_order

    • Description: Get detailed order information
    • Parameters: orderId, expand

  • swell_update_order_status

    • Description: Update the status of an order (with optional notes)
    • Parameters: orderId, status, notes
Customer Management

  • swell_list_customers

    • Description: List customers with search and filtering options
    • Parameters: page, limit, search, email, dateFrom, dateTo, sort, expand

  • swell_get_customer

    • Description: Get detailed customer information (profile + optional order history)
    • Parameters: customerId, expand, includeOrderHistory

  • swell_search_customers

    • Description: Search customers using text queries (name, email, phone)
    • Parameters: query, page, limit, dateFrom, dateTo, sort, expand

  • swell_update_customer

    • Description: Update customer records (name, email, phone, tags, groups, marketing opt-ins, notes)
    • Parameters: customerId plus editable customer fields

Extending the Server

This server is built with a modular architecture that makes it easy to add new Swell API integrations or custom business logic. The existing Swell tools (products, orders, customers) serve as examples for implementing additional functionality.

For detailed implementation patterns, see the existing controllers, services, and tools in the codebase.

Standalone Usage

If you want to run the server independently (not through an MCP client):

Global Installation

npm install -g swell-mcp

Direct Usage

# Set your credentials
export SWELL_STORE_ID=your-store-id
export SWELL_SECRET_KEY=your-secret-key

# Run the server
swell-mcp

HTTP Mode

# Run with HTTP transport on port 3000
TRANSPORT_MODE=http swell-mcp

# Custom port
PORT=8080 TRANSPORT_MODE=http swell-mcp

πŸš€ Take Your Swell Store Further

Impressed by this MCP server's capabilities? This is just a glimpse of what's possible with expert Swell development.

οΏ½ CheckoutJet - Enterprise Swell Checkout

Transform your Swell store with our battle-tested checkout solution:

  • B2B Powerhouse - Professional invoicing, Net 30 payments, wholesale pricing
  • Smart Shipping - Live rates from multiple locations with intelligent routing
  • Split Deliveries - Complex multi-vendor and multi-warehouse fulfillment
  • Full Customization - Pixel-perfect, on-brand checkout experience
  • Proven Results - €500,000+ processed, 23% conversion improvements

See CheckoutJet in Action β†’

πŸ€– AI & Custom Development

  • AI-powered integrations like this MCP server
  • Custom Swell applications and themes
  • Headless commerce implementations
  • Performance optimization and automation

Ready to transform your e-commerce business?

See CheckoutJet Demo

Testing Strategy

The server includes comprehensive testing infrastructure:

Test Structure

tests/               # Not present - tests are in src/
src/
β”œβ”€β”€ **/*.test.ts     # Co-located with source files
β”œβ”€β”€ utils/           # Utility function tests
β”œβ”€β”€ controllers/     # Business logic tests
β”œβ”€β”€ services/        # API integration tests
└── cli/             # CLI command tests

Testing Best Practices

  • Unit Tests: Test utilities and pure functions (*.util.test.ts)
  • Controller Tests: Test business logic with mocked service calls
  • Service Tests: Test API integration with real/mocked HTTP calls
  • CLI Tests: Test command parsing and execution
  • Test Environment Detection: Automatic test mode handling in controllers

Running Tests

npm test                    # Run all tests
npm run test:coverage       # Generate coverage report
npm run test:cli           # CLI-specific tests only

Coverage Goals

  • Target: >80% test coverage
  • Focus on business logic (controllers) and utilities
  • Mock external services appropriately

License

ISC License

Resources & Documentation

MCP Protocol Resources

Implementation References

Swell Resources

Professional Swell Services

Looking for expert Swell development? Devkind is an official Swell partner serving businesses globally with our remote team, specializing in:

Get Started: See CheckoutJet Demo | Book FREE consultation | Email: hello@devkind.com.au | Global Remote Team

About

Model Context Protocol (MCP) server for Swell e-commerce platform integration with AI assistants

Topics

ecommerce ai checkout mcp headless assistant swell mcp-server swell-mcp

Resources

Readme
Activity
Custom properties

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 1

v1.0.8 Latest
Oct 11, 2025

Packages

 
 
 

Contributors

Languages