Purpose
W3Ship Commerce MCP Server is an MCP (Model Context Protocol) server for AI-driven commerce, with the goal of enabling AI agents to complete operations such as shopping, placing orders, logistics tracking, appointments, token swaps, and P2P transactions on behalf of users. Users do not need a password or login; they can complete the above processes using only a cryptographic identity.
Main Capabilities
This server provides a total of 22 tools, covering the following modules:
- Shopping cart (TMF663): Create and manage shopping carts.
- Orders (TMF622): Place and manage orders.
- Logistics tracking (TMF621): Track delivery status.
- Session appointments: Book service sessions; requests are forwarded to the w3ship.com API.
- Identity queries: Identity query requests are forwarded to the centralized W3Ship API (w3ship.com/api/identity); signature verification and database access are both completed server-side, and no AWS credentials are required on the user side.
- Uniswap Swap (new in v1.3.0): Requires UNISWAP_API_KEY, which can be obtained for free at developers.uniswap.org. Built-in token addresses on the Base chain include ETH, USDC, USDT, DAI, and WETH; other tokens can be passed in as any ERC-20 contract address.
- P2P marketplace (new in v1.4.0): Product categories include electronics, clothing, collectibles, home, sports, gifts, books, and other; any user with a wallet address is a merchant.
- Payment and fulfillment (new in v1.4.0): P2P orders automatically recognize listed products (LST-* prefix), fill in the seller's wallet address, and set the payment status to awaiting_payment; after payment is completed, the seller uses add_tracking to provide logistics information.
- Promotional products and pickup (updated in v1.6.0): Promotional listings support three fulfillment modes; v1.6.0 adds in-store pickup, and the AI returns the pickup location, business hours, and instructions; pickup claims do not require registering an address, only a wallet identity.
How to Use
Install via npx (recommended); no installation is required, only configuration of the AI client:
- Claude Desktop: Configure claude_desktop_config.json
- Cursor: Configure .cursor/mcp.json
- VS Code: Configure .vscode/mcp.json
Environment requirements: A Redis / Valkey instance is required (for shopping cart, order, and logistics storage). Locally, it can be run via docker run -p 6379:6379 redis:latest, or any Redis-compatible service can be used (AWS ElastiCache, Upstash, etc.).
Related environment variables and key acquisition:
- MetaMask users: Simply copy the Ethereum address (e.g., 0x1234...abcd) and use it.
- Dah.mx users: Settings → AI Assistant Setup → copy the key.
- Demo/testing: Do not set a key; use generate_demo_key in the AI assistant.
- For production use, it is recommended to set a real wallet key via W3SHIP_PUBLIC_KEY in the MCP configuration.
Cryptographic identity: W3Ship uses cryptographic identity, with no username, no password, and no account, and supports three identity types; the wallet address or public key is the shopping cart ID, and no registration is required.
Architecture
The MCP server is a light client that combines local shopping cart/order storage with centralized W3Ship services:
- Commerce (shopping cart, orders, logistics) → stored in local Redis
- Identity (address queries) → forwarded to the w3ship.com API
- Session appointments → forwarded to the w3ship.com API
No AWS credentials are required on the user side, and no cloud configuration is required.
Applicable Scenarios
Suitable for users and developers who want AI agents to complete the shopping process, order and logistics management, service appointments, token swaps, P2P buying and selling, and promotional product claims and in-store pickup on their behalf, and especially suitable for scenarios that prefer using wallet identity rather than an account system for authentication.
Limitations
The materials do not provide functionality, fees, pricing, platform compatibility, or effect descriptions beyond the above content; related details are not yet provided. The project license is MIT; see the LICENSE file for details.
