W3Ship Commerce MCP Server

Let AI shop for you — with no passwords, no logins, just cryptographic identity.

W3Ship is the first MCP (Model Context Protocol) server for AI-powered commerce. It gives AI agents like Claude, Cursor, and VS Code Copilot the ability to create shopping carts, place orders, track shipments, book sessions, swap tokens via Uniswap, sell items P2P, and distribute promotional items with in-store pickup — all using cryptographic identity (SLH-DSA / ECDSA) instead of passwords.

Built on TMF Open API standards (TMF663, TMF622, TMF621) for interoperability.

⚡ Quick Start

Install via npx (recommended)

No installation required — just configure your AI client:

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "w3ship": {
      "command": "npx",
      "args": ["-y", "w3ship-mcp-server"],
      "env": {
        "VALKEY_HOST": "localhost",
        "VALKEY_PORT": "6379"
      }
    }
  }
}

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "w3ship": {
      "command": "npx",
      "args": ["-y", "w3ship-mcp-server"],
      "env": {
        "VALKEY_HOST": "localhost",
        "VALKEY_PORT": "6379"
      }
    }
  }
}

VS Code (.vscode/mcp.json):

{
  "servers": {
    "w3ship": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "w3ship-mcp-server"],
      "env": {
        "VALKEY_HOST": "localhost",
        "VALKEY_PORT": "6379"
      }
    }
  }
}

Prerequisites

• Node.js 18+
• Redis / Valkey instance (for cart, order, and shipment storage)
  • Local: docker run -p 6379:6379 redis:latest
  • Or any Redis-compatible service (AWS ElastiCache, Upstash, etc.)

🛠️ Tools (22 total)

🛒 Shopping Cart (TMF663)

📦 Orders (TMF622)

🚚 Shipment Tracking (TMF621)

📅 Session Booking

🔐 Identity Lookup

Identity lookups are forwarded to the centralized W3Ship API (w3ship.com/api/identity). Signature verification and database access happen server-side — no AWS credentials needed on your end.

🧪 Setup & Demo

🔄 Uniswap Swap (NEW in v1.3.0)

Requires UNISWAP_API_KEY — get yours free at developers.uniswap.org. Built-in token addresses for Base chain: ETH, USDC, USDT, DAI, WETH. Pass any ERC-20 contract address for other tokens.

🏪 P2P Marketplace (NEW in v1.4.0)

Categories: electronics, clothing, collectibles, home, sports, gifts, books, other. Anyone with a wallet address is a merchant.

💳 Payment & Fulfillment (NEW in v1.4.0)

P2P orders auto-detect listing items (LST-* prefix), fill in seller wallet address, and set payment status to awaiting_payment. After payment, sellers use add_tracking to provide shipping info.

🎁 Promotional Items & Pickup (Updated in v1.6.0)

New in v1.6.0: In-Store Pickup

Promo listings now support three fulfillment modes:

Mode	How It Works
ship	Customer pays shipping, item mailed (original flow)
pickup	Customer picks up at a physical location — zero cost
both	Customer chooses shipping or pickup

Create a pickup promo:

Code

Copy

create_listing(
  isPromo: true,
  fulfillmentType: "pickup",
  pickupLocations: [{
    id: "qbm",
    name: "Quaker Bridge Mall",
    address: "3320 Brunswick Pike, Lawrenceville NJ",
    hours: "Mon-Sat 10am-9pm",
    instructions: "Visit the kiosk near the food court. Show your claim ID."
  }]
)

Claim with pickup:

Code

Copy

claim_promo(listingId: "...", fulfillmentChoice: "pickup", pickupLocationId: "qbm")

The AI returns the pickup location, hours, and instructions. No address registration needed for pickup claims — only wallet identity is required.

🔐 Cryptographic Identity

W3Ship uses cryptographic identity — no usernames, no passwords, no accounts. Three identity types are supported:

Your wallet address or public key IS your cart ID. No sign-up required.

⚙️ Configuration

Environment Variables

Getting Your Key

• MetaMask users: Just copy your Ethereum address (e.g. 0x1234...abcd) — it works directly
• Dah.mx users: Settings → AI Assistant Setup → Copy key
• Demo/Testing: Don't set a key — use generate_demo_key in your AI assistant instead

🏗️ Architecture

The MCP server is a thin client that combines local cart/order storage with centralized W3Ship services:

┌─────────────────────────────────────────────┐
│  AI Client (Claude / Cursor / VS Code)      │
│  "Create a cart and book a fitness session"  │
└──────────────────┬──────────────────────────┘
                   │ stdio (MCP Protocol)
┌──────────────────▼──────────────────────────┐
│  W3Ship MCP Server (your machine)           │
│                                              │
│  Local Storage (Redis/Valkey):               │
│  ┌──────────┐ ┌─────────┐ ┌──────────────┐  │
│  │ Cart     │ │ Orders  │ │ Shipment     │  │
│  │ (TMF663) │ │ (TMF622)│ │ (TMF621)     │  │
│  └──────────┘ └─────────┘ └──────────────┘  │
│                                              │
│  Centralized API (w3ship.com):               │
│  ┌──────────────┐  ┌─────────────────────┐  │
│  │ Booking      │  │ Identity Lookup     │  │
│  │ /api/slots   │  │ /api/identity       │  │
│  └──────────────┘  └─────────────────────┘  │
└──────────────────────────────────────────────┘

• Commerce (cart, order, shipment) → stored locally in your Redis
• Identity (address lookup) → forwarded to w3ship.com API
• Session Booking → forwarded to w3ship.com API
• No AWS credentials needed. No cloud config required.

💡 Example Conversations

Shopping & Booking

You:    "I want to shop on W3Ship"
Claude: [calls get_identity — no key configured]
        [calls generate_demo_key — creates a test identity]
        [calls create_cart with the demo key]
        "You're all set! I've created a shopping cart for you.
         What would you like to buy?"

You:    "Book me a VR session for this afternoon"
Claude: [calls get_available_slots for today]
        "Here are today's sessions at Downtown VR:
         • 2:00 PM - $45 (3 spots left)
         • 4:00 PM - $45 (5 spots left)
         Which time works?"

You:    "4 PM"
Claude: [calls hold_slot → add_item]
        "Slot held for 10 minutes. Added to your cart."