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)

Tool	Description
create_cart	Create a shopping cart. Uses W3SHIP_PUBLIC_KEY automatically if configured
get_cart	Retrieve a cart by its public key ID
add_item	Add an item (product offering + quantity) to a cart
delete_cart	Delete a shopping cart

📦 Orders (TMF622)

Tool	Description
create_order	Convert a cart into a confirmed order and initiate fulfillment
get_order	Retrieve order details by order ID

🚚 Shipment Tracking (TMF621)

Tool	Description
track_shipment	Track delivery status with simulated real-time updates

📅 Session Booking

Tool	Description
get_available_slots	Get available session time slots by location and date (VR, fitness, dining, salon, etc.)
hold_slot	Reserve a session slot (held for 10 minutes pending payment)
list_bookings	List confirmed bookings, optionally filtered by location/date

🔐 Identity Lookup

Tool	Description
ship_address	Retrieve a physical shipping address using a public key + timed signature

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

Tool	Description
generate_demo_key	Generate a demo ECDSA key pair for testing — try the commerce flow without a wallet
get_identity	Show the currently configured identity or instructions on how to set one up

🔄 Uniswap Swap (NEW in v1.3.0)

Tool	Description
get_swap_quote	Get a swap quote from Uniswap — returns output amount, gas estimate, price impact, and routing path. Supports V2, V3, V4, and UniswapX. Default chain: Base (8453).
check_token_approval	Check if a token is approved for swapping on Uniswap. Returns approval transaction data if needed.

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)

Tool	Description
create_listing	Sell anything — no merchant onboarding needed. Set title, price, currency, and your wallet address for payment. Listings expire after 30 days by default.
search_listings	Browse active listings by category (electronics, gifts, clothing, etc.) or keyword search.
get_listing	Get full details of a listing: description, price, seller, payment address, shipping regions.
remove_listing	Remove your own listing. Seller address must match.

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

💳 Payment & Fulfillment (NEW in v1.4.0)

Tool	Description
confirm_payment	Submit an on-chain transaction hash to verify payment. Supports Base (8453) and Tempo chains. Updates order to "paid".
add_tracking	Seller provides real carrier tracking (UPS, FedEx, USPS, DHL, etc.) after shipping the item.

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)

Tool	Description
claim_promo	Claim a FREE promotional listing. Supports shipping or in-store pickup. One per wallet.

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:

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:

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:

Scheme	Key Size	Use Case
EVM Address	20 bytes (40 hex chars)	MetaMask / any Ethereum wallet
ECDSA (P-256)	33 bytes (compressed) / 65 bytes (uncompressed)	Standard web3 wallets
SLH-DSA	32 bytes (64 hex chars)	Post-quantum secure identity (Dah.mx)

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

---

⚙️ Configuration

Environment Variables

Variable	Required	Default	Description
W3SHIP_PUBLIC_KEY	No	—	Your wallet address or public key (hex). Set once and all tools use it automatically
UNISWAP_API_KEY	No	—	Uniswap Trading API key for swap quotes. Get yours at developers.uniswap.org
VALKEY_HOST	No	localhost	Redis/Valkey host
VALKEY_PORT	No	6379	Redis/Valkey port
VALKEY_PASSWORD	No	—	Redis/Valkey password (if auth enabled)
W3SHIP_API_URL	No	https://w3ship.com	Base URL for the W3Ship API (identity, session booking)

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."

You:    "Place the order"
Claude: [calls create_order]
        "Order confirmed! Tracking: TRK-8392751046"

Claiming a Promo with Pickup (NEW in v1.6.0)

You:    "Any free promos I can grab?"
Claude: [calls search_listings with category: promotional]
        "There's a free VR Experience Card available!
         You can pick it up at Quaker Bridge Mall."

You:    "I'll take it"
Claude: [calls claim_promo with fulfillmentChoice: pickup]
        "Claimed! Here's your pickup info:
         📍 Quaker Bridge Mall, Lawrenceville NJ
         🕐 Mon-Sat 10am-9pm
         🎟️ Claim ID: CLM-MMB1ZW3W-W98I
         Show your claim ID at the VR kiosk near the food court."

Tip: For production use, set your real wallet key via W3SHIP_PUBLIC_KEY in your MCP config. See Getting Your Public Key above.

---

📰 Press

• TechBullion: How W3Ship Works: The MCP Server That Turns Any AI Into a Merchant
• Digital Journal: Quantum-Resistant Commerce Token Launches via Uniswap CCA on Unichain
• Syndicated across 500+ outlets — full coverage →

---

🔗 Links

• Website: w3ship.com
• Press: w3ship.com/press
• GitHub: github.com/baskcart/w3ship
• W3SH Token: Uniswap CCA Auction

---

📄 License

MIT — see LICENSE