Swell

You can connect your AI assistant to Swell’s e-commerce platform through a dedicated MCP server. This server exposes the Swell API for products, orders, and customers via a type-safe, dual-transport MCP interface, enabling conversational store management and automation inside your preferred MCP client.

How to use

You integrate the Swell MCP Server with your MCP client (for example Claude Desktop, Cursor, or VS Code) to perform store actions through natural language interactions. Use it to list products, view orders, inspect customers, and update records. Each command is exposed as an MCP tool with clear inputs and structured outputs, so your assistant can guide you through store tasks without direct API coding.

How to install

Prerequisites you need before installing are: Node.js 18 or newer, an MCP client or environment (such as Claude Desktop, Cursor, Windsurf, or Warp), and your Swell store credentials.

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

# 2) Install dependencies
npm install

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

# 4) Build the project
npm run build

# 5) Run in STDIO transport for local AI assistants
npm run mcp:stdio

# Optional: run in HTTP transport for web integrations
# npm run mcp:http

To use a ready-made JSON configuration for an MCP client, place this in your MCP setup file to run the server via the standard method:

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

Additional steps for different MCP clients

Claude Desktop, Cursor, Windsurf, Warp, and other MCP clients offer built-in ways to add an MCP server. Use the standard configuration above as a starting point and adapt the environment variables to your Swell credentials. Each client provides a dedicated place to paste the JSON configuration or to enter the command and arguments for starting the server.

Configuration

Getting your Swell credentials is essential to authorize API access. Obtain them from your Swell dashboard under Developer → API Keys. You will need your Store ID and Secret Key.

Environment variables you will use in the server and MCP client are:

{
  "SWELL_STORE_ID": "your-store-id",
  "SWELL_SECRET_KEY": "your-secret-key",
  "DEBUG": "false"  // optional: set to true for verbose responses
}

Usage tips

Enable debug mode if you want to see raw responses during development by setting DEBUG to true in your environment. The HTTP transport exposes an MCP endpoint at /mcp and health at /. You can switch transports with the TRANSPORT_MODE variable and choose a port with PORT.

Security and access

Treat your Swell credentials as secrets. Do not expose SWELL_STORE_ID or SWELL_SECRET_KEY in public code or logs. Use environment variable management in your MCP client and restrict server access to trusted clients.

Available 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

swell_update_customer

Update customer records (name, email, etc.)