Skip to main content
Glama
NyokolodiK

ecommerce-mcp

by NyokolodiK
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

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.AsyncClient with retry + exponential backoff for connection errors and 5xx

  • Typed 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 schemas

  • Session-persistent carts — lock-protected in-memory store, safe under concurrent tool calls

  • Layered architecture — thin FastMCP entrypoint over isolated models, services, and tools layers

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 tests

Requirements

  • 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            # typecheck

Configuration

.env is loaded by pydantic-settings at server start:

Variable

Default

Description

STORE_API_BASE_URL

https://fakestoreapi.com

Upstream store API base URL

STORE_API_TIMEOUT_SECONDS

10

Per-request read/connect timeout

STORE_API_MAX_RETRIES

2

Retries for connection errors and 5xx

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-stream

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

list_products

Paginated catalog search (limit 1–100, offset ≥ 0)

get_product

Single product by id (≥ 1)

create_cart

New empty cart

get_cart

Snapshot of a cart

add_to_cart

Add/merge a product line (max 999 units/line)

update_cart_item

Overwrite a line quantity

remove_cart_item

Remove a line entirely

checkout

Place an order; returns OrderConfirmation with computed shipping/tax/total

Install Server
F
license - not found
A
quality
B
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

Related MCP Servers

  • FakeStore MCP

    Mithgroth
    F
    license
    -
    quality
    D
    maintenance
    A 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.

  • UCP MCP Storefront

    ZaynTawfik
    A
    license
    A
    quality
    C
    maintenance
    A UCP-compliant MCP storefront server that exposes product catalog operations (search, cart, checkout) as MCP tools, following UCP schema version 2026-04-08.
    5
    MIT

View all related MCP servers

Related MCP Connectors

  • MCP Commerce Server Starter

    FastMCP commerce server starter: product catalog, search, and checkout. Deploy to Vercel in 5 min.

  • mockmcp

    Hosted MCP endpoint with realistic fake data for prototyping agents. 12 tools, no setup.

  • MedPrice AI

    Hosted MCP server exposing US hospital procedure cost data to AI assistants

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/NyokolodiK/ecommerce-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server