ecommerce-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ecommerce-mcp Find electronics under $50 and add the first result to my cart."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
E-commerce MCP Server
Enterprise-ready Model Context Protocol server exposing catalog, cart, and checkout tools over FastMCP, backed by the public Fake Store API.
Features
8 MCP tools — catalog search, cart lifecycle, and checkout with order confirmation
Strict Pydantic contracts — validated inputs (range/length constraints) and structured outputs, never raw strings
Async everywhere —
httpx.AsyncClientwith retry + exponential backoff for connection errors and5xxTyped error taxonomy — upstream failures surface as structured, human-readable tool errors
Fake Store adapter — transparently maps Fake Store's native payloads (plain arrays,
title/category/image, no pagination, no order endpoint) onto the project's schemasSession-persistent carts — lock-protected in-memory store, safe under concurrent tool calls
Layered architecture — thin FastMCP entrypoint over isolated
models,services, andtoolslayers
Related MCP server: Online Boutique AI Assistant MCP Server
Architecture
src/
├── server.py # Thin entrypoint: DI wiring + FastMCP registration (stdio + HTTP)
├── models/ # Strict Pydantic data contracts
│ ├── product.py # Product, ProductSummary, ProductListResponse
│ ├── cart.py # Cart, CartItem
│ └── checkout.py # CheckoutRequest, OrderConfirmation, pricing helpers
├── services/ # External I/O and mutable state
│ ├── store_api.py # Typed async client w/ retry, error taxonomy, Fake Store adapter
│ └── cart_store.py # Lock-protected, session-persistent cart store
└── tools/ # Class-based FastMCP tool handlers
├── catalog.py # list_products, get_product
├── cart.py # create_cart, get_cart, add_to_cart, update_cart_item, remove_cart_item
└── checkout.py # checkout
tests/
├── test_models.py # Model + pricing unit tests
├── test_server.py # Tool-surface integration tests (respx-mocked upstream)
└── test_fakestore_adapter.py # Fake Store payload adaptation testsRequirements
Python >= 3.11
uv (package manager)
Setup
uv sync # install deps (incl. dev group)
# .env is tracked; edit STORE_API_* values if you target a different upstream
uv run pytest # 57 tests
uv run ruff check . # lint
uv run mypy src tests # typecheckConfiguration
.env is loaded by pydantic-settings at server start:
Variable | Default | Description |
|
| Upstream store API base URL |
|
| Per-request read/connect timeout |
|
| Retries for connection errors and |
When the base URL points at fakestoreapi.com, the client auto-adapts:
title → name, float price → decimal string, category → categories, image → image URL, rating.count → stock approximation; catalog pages are paginated locally; checkout submits to POST /carts (Fake Store has no order endpoint) and returns a locally-computed OrderConfirmation. Any other base URL is consumed as-is (paginated {items, total, limit, offset} listing and POST /orders).
Running the server
stdio (default MCP transport)
uv run python -c "import sys; sys.path.insert(0, 'src'); from server import main; main()"HTTP (Streamable HTTP, for Postman / remote clients)
uv run python -c "import sys; sys.path.insert(0, 'src'); from server import main_http; main_http()"Serves POST http://127.0.0.1:8765/mcp.
Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"ecommerce-mcp": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/ecommerce-mcp",
"run",
"python",
"-c",
"import sys; sys.path.insert(0, 'src'); from server import main; main()"
]
}
}
}Restart Claude Desktop, then try: "List products", "Add 2 of product 1 to a cart", "Checkout with Ada Lovelace, ada@example.com, London GB, card".
Testing with Postman
The HTTP transport is session-based MCP. Send every request to POST http://127.0.0.1:8765/mcp with headers:
Content-Type: application/json
Accept: application/json, text/event-stream1. Initialize (capture the mcp-session-id response header, then send it on all later requests):
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"postman","version":"1.0"}}}2. List tools:
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}3. Call a tool:
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"list_products","arguments":{"limit":5,"offset":0}}}Suggested demo flow: list_products → create_cart → add_to_cart → get_cart → checkout.
Tools
Tool | Description |
| Paginated catalog search ( |
| Single product by id (≥ 1) |
| New empty cart |
| Snapshot of a cart |
| Add/merge a product line (max 999 units/line) |
| Overwrite a line quantity |
| Remove a line entirely |
| Place an order; returns |
Available Tools
8 toolsadd_to_cartA
Add a product to a cart, merging with an existing line.
Inputs: cart_id (required), request (required). Returns: A shopping cart owned by a client session.
checkoutA
Place an order from a cart and confirm it with the store.
Inputs: request (required). Returns: Structured confirmation returned after a successful checkout.
create_cartA
Start a new shopping session and return an empty cart.
Inputs: no named parameters. Returns: A shopping cart owned by a client session.
get_cartA
Read the current contents of a cart.
Inputs: cart_id (required). Returns: A shopping cart owned by a client session.
get_productA
Fetch a single product by its numeric identifier.
Inputs: product_id (required). Returns: A single catalog product as exposed to MCP clients.
list_productsB
Search the product catalog with pagination.
Inputs: limit, offset. Returns: Paginated result set returned by catalog search tools.
remove_cart_itemA
Remove a product line from a cart entirely.
Inputs: cart_id (required), product_id (required). Returns: A shopping cart owned by a client session.
update_cart_itemA
Overwrite the quantity of a product line in a cart.
Inputs: cart_id (required), request (required). Returns: A shopping cart owned by a client session.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool targets a distinct action-resource pair: products (list/get), cart operations (create/get/add/update/remove), and checkout. No two tools overlap in purpose, making selection unambiguous.
All tools follow a consistent verb_noun pattern (list_products, get_product, create_cart, update_cart_item, remove_cart_item). 'checkout' is a clear, standard verb for the action, and the overall naming is predictable and readable.
With 8 tools, the server is well-scoped for ecommerce cart and catalog management. Each tool covers a necessary operation without redundancy or bloat, fitting the typical ideal range.
The tool set covers the full lifecycle of a cart (create, read, add/update/remove items, checkout) and product browsing (list, get). Minor gaps include no explicit delete-cart or order-history tool, but these are not critical for the core shopping flow.
Maintenance
Related MCP Connectors
Sample shop MCP server: paginated search, idempotent orders, guarded cancellation. Four languages.
Hosted MCP for e-commerce: live product catalog, stock, and pricing for AI agents.
Hosted MCP server for AI-driven data ops. Create apps, manage schemas, and CRUD structured data.
FastMCP commerce server starter: product catalog, search, and checkout. Deploy to Vercel in 5 min.
Related MCP Servers
- FlicenseNot gradedqualityFmaintenanceA Model Context Protocol server that enables AI assistants to interact with a complete e-commerce application, providing authentication, product browsing, and shopping cart management through standardized MCP tools.-
- AlicenseNot gradedqualityDmaintenanceMCP server for Online Boutique AI Assistant that exposes 18 e-commerce microservice functions via the Model Context Protocol, enabling any MCP client to manage products, carts, checkout, payments, and shipping.33 PyPIMIT
- AlicenseAqualityDmaintenanceA UCP-compliant MCP storefront server that exposes product catalog operations (search, cart, checkout) as MCP tools, following UCP schema version 2026-04-08.5MIT
- FlicenseNot gradedqualityDmaintenanceDemo MCP server that exposes order and customer data as read-only tools for AI assistants, simulating a business API or internal data source.-