Skip to main content
Glama
SMCodesP

AliExpress MCP

by SMCodesP
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

AliExpress MCP

A self-hosted MCP server that lets an LLM search AliExpress and inspect product listings — with no API key.

AliExpress has no official public product-search API, so this server mirrors what the aliexpress.com web frontend does:

  • Search — fetches the server-rendered search page (/w/wholesale-<query>.html) and pulls the product list out of the _init_data_ JSON the page embeds for its own hydration. On an anti-bot (TMD) punish page it falls back to loading the same URL in a headless browser.

  • Product detail — tries AliExpress's internal MTop API (acs.aliexpress.com) first, which needs an _m_h5_tk token (bootstrapped on the first request) and an MD5 request signature MD5(token & timestamp & appKey & data). MTop is anti-bot gated for plain HTTP clients today, so a headless Chromium loads the product page and the server intercepts the very same MTop response the page fetches for itself. See how product detail is fetched.

TLS fingerprinting via curl_cffi (Chrome impersonation) is usually enough for search, which tries a plain HTTP call first. Product detail is gated on executed JavaScript rather than TLS fingerprint, so it needs a real browser (headless Chromium, via patchright); search falls back to the same browser transport when its plain HTTP call is anti-bot challenged.

It is read-only: it searches and reads listings, it cannot buy.

Tools

Tool

Purpose

search_aliexpress

Keyword search with optional sort (orders, price_asc, price_desc, newest), min_price / max_price, and page. Returns products with id, title, price, currency, rating, orders-sold, image and URL.

get_aliexpress_product

Full record for a numeric product id or a full product URL: title, selected + per-variant prices, rating, review count, orders, stock, store, shipping, SKU option axes, specs and all images. Served via MTop or the browser transport (source: "mtop" / "browser", partial: false). If both are unavailable it degrades to source: "ssr+search", partial: true — title, images, url, price, rating and orders, with everything else named in unavailable.

Responses are shaped as clean dicts ({query, returned, total, items: [...]} for search). On an anti-bot block or a transport error the tool returns {"error": "..."} rather than raising.

How product detail is fetched (and why a browser)

As of 2026-08-08 AliExpress answers the MTop product-detail endpoints (mtop.aliexpress.pdp.pc.query, …itemdetail.pc.asyncPCDetail) with FAIL_SYS_USER_VALIDATE / RGV587_ERROR and a captcha url instead of data, when called over plain HTTP. Four things were checked rather than assumed:

  • Not an IP-reputation problem. A residential IP is refused exactly like a datacenter one, in the same minute.

  • Not a token or signing regression. mtop.relationrecommend.aliexpressrecommend.recommend still mints an _m_h5_tk normally, and signing the pdp call with that fresh token is refused just the same.

  • Not login-gated, and the endpoint is not dead. A real Chromium — not logged in, on the same IP, and headless at that — gets SUCCESS and a ~95 KB payload from that exact endpoint. What the anti-bot wants is the JavaScript executed; curl_cffi's Chrome TLS impersonation is not enough on its own.

  • The product page cannot stand in for it. /item/<id>.html is now client-side rendered, ships an empty window.runParams, and fetches its own data from that same endpoint.

So detail uses three transports, cheapest first:

#

Transport

Result

1

Direct MTop over HTTP

Currently gated. Still tried first, so the cheap path resumes automatically if AliExpress ungates it

2

Browser — load the page, intercept its own pdp.pc.query response

Full record. ~2 s warm. source: "browser"

3

SSR composite — product page + search results

Partial. Only if the browser is disabled or fails. source: "ssr+search", partial: true

Transport 2 does not reimplement the anti-bot JavaScript; it just reads the answer the page already obtains for itself. The payload is byte-identical to what direct MTop used to return, so the same parser handles it unchanged.

Two behaviours here were measured, not guessed, and both are counter-intuitive:

  • A fresh browser context per lookup, not a warm one. Reusing a context got the second back-to-back lookup answered with RGV587, while the first request of a fresh context succeeds. Carried-over state is what marks you.

  • Bail out the instant RGV587 arrives. The page will not retry itself, so waiting out the timeout buys nothing — detecting it and retrying in a fresh context turns a 45 s dead wait into a ~2 s retry. AliExpress challenges a proportion of loads rather than locking on, so a capped retry (AE_BROWSER_ATTEMPTS, default 3) recovers almost all of them.

Related MCP server: MCP Shop Server

Market (Germany / EUR by default)

Prices, currency and localisation follow the target market, set by three env vars (defaults in bold):

Env var

Default

Meaning

AE_REGION

DE

Ship-to region (e.g. BR for Brazil)

AE_CURRENCY

EUR

Display currency (e.g. BRL for Brazilian Real)

AE_LOCALE

de_DE

Language / localisation (e.g. pt_BR for Portuguese)

ALIEXPRESS_COOKIE

none

Full cookie string or session cookies (aep_usuc_f, xman_t, etc.) to bypass anti-bot / TMD punish page

AE_COOKIE_FILE

~/.gemini/config/aliexpress_cookie.txt

Path to a text file containing the AliExpress cookie string

AE_MAX_CONCURRENT

2

Process-wide cap on concurrent requests to AliExpress.

AE_MTOP_COOLDOWN

900

Seconds to stop attempting MTop product detail after it answers with an anti-bot challenge.

AE_BROWSER_ENABLED

true

Browser transport for product detail.

AE_BROWSER_ATTEMPTS

3

Attempts per lookup, each in a fresh context.

AE_BROWSER_RETRY_DELAY_S

1.5

Pause between attempts.

AE_BROWSER_TIMEOUT_MS

45000

Per-attempt budget.

AE_BROWSER_HEADLESS

true

Headless mode for Chromium.

These are pushed to AliExpress via the aep_usuc_f cookie (search) and the _lang / _currency / country MTop params (product detail). Any custom cookies provided via ALIEXPRESS_COOKIE or AE_COOKIE_FILE are also injected into both HTTP session and browser contexts to prevent anti-bot verification challenges.

Run

docker run --rm -p 8000:8000 ghcr.io/jnslmk/aliexpress-mcp:latest
# streamable-HTTP MCP endpoint: http://127.0.0.1:8000/mcp
# health:                       http://127.0.0.1:8000/healthz

Transport is streamable-HTTP by default (MCP_TRANSPORT=http, :8000/mcp); set MCP_TRANSPORT=stdio for a classic stdio MCP server. See .env.example.

/healthz always returns 200 {"status":"ok", ...} while the process is up — there is no credential or hard dependency to gate on. A blocked AliExpress upstream is a per-request condition surfaced in the tool response, not container ill-health.

Caveats

This talks to undocumented AliExpress endpoints. That is inherent to the problem (there is no official API), but it means:

  • AliExpress can change the embedded-JSON shape or the MTop signing scheme at any time and break extraction. Every extractor is written defensively and failures degrade to a clear error.

  • Datacenter IPs are challenged more aggressively than residential ones. From some hosts AliExpress returns an anti-bot (x5sec / RGV587 / TMD punish) response to search. Search tries the same cheap plain-HTTP call first and, on a TMD punish page, falls back to the browser transport loading the identical search URL — the same trade AliExpress applies to product detail. If the browser gets challenged too, or AE_BROWSER_ENABLED=false, the tool reports a block.

  • A residential IP is not immunity — volume still trips the block. While developing 0.2.0 a burst of exploratory requests earned a TMD punish page on a residential connection that lasted well over an hour, taking search down with it. AE_MAX_CONCURRENT (default 2) caps concurrency, but nothing caps your total rate; if you are probing, go slowly and expect a long cooldown when you get it wrong.

  • Be a good citizen: low request volume only.

Credits

The AliExpress access approach (MTop token bootstrap + MD5 signing, and _init_data_ search parsing) is ported from Averyy/fetchaller-mcp (MIT). Transport/packaging mirror the sibling jnslmk/ebay-mcp.

License

MIT — see LICENSE.

Available Tools

2 tools
get_aliexpress_productGet Aliexpress ProductA

Retrieve the record of one AliExpress product.

Use after search_aliexpress surfaces something worth a closer look.

How complete the answer is depends on which source could serve it, so check the source and partial fields before describing it to the user:

  • source: "mtop", partial: false — the full record: title, selected-variant price plus per-variant pricing, star rating and review count, orders sold, stock, the store (name, positive rating, country), shipping (origin, ship-to, delivery estimate), the SKU option axes (e.g. colour / size), specifications and all product images.

  • source: "ssr+search", partial: true — AliExpress is currently gating its detail API behind an anti-bot challenge, so the record is composed from the product page and search results: title, images, url, price, rating and orders. Every field that could not be obtained is named in unavailable. Occasionally even price/rating cannot be recovered; price_note explains why and search_status distinguishes the two causes — blocked (AliExpress is rate-limiting right now, so it is worth retrying later) from not_found (the listing genuinely did not turn up in search). Say which one it was rather than just "no price available".

Prices are in the configured currency (EUR by default). A field listed in unavailable is unknown, not absent from the listing — do not tell the user a product has no variants, no reviews or no shipping options on that basis; say that detail could not be retrieved.

ParametersJSON Schema
NameRequiredDescriptionDefault
productYesAliExpress product id (a numeric string such as '1005009258005772') or a full product URL like 'https://www.aliexpress.com/item/1005009258005772.html'.

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It thoroughly explains that the response can be full (`source: "mtop"`) or partial (`source: "ssr+search"`), describes the anti-bot gating, and clarifies how to interpret `unavailable`, `price_note`, and `search_status` (including the `blocked` vs `not_found` distinction). It also notes the currency configuration. This goes far beyond a generic read-only hint and gives the agent actionable knowledge about edge cases.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is longer than average, but it is well-structured and front-loaded. The core purpose and usage trigger are in the first two sentences, followed by a bulleted breakdown of response sources and interpretive guidance. Each sentence earns its place – there is no redundancy or filler, and the formatting makes the conditional logic easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity and the presence of an output schema, the description is exceptionally complete. It covers the two possible response shapes, how to distinguish unknown fields from truly absent ones, how to handle price retrieval failures, and even how to communicate results to the user. The agent has everything it needs to invoke the tool and interpret the response correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already provides a complete description of the `product` parameter, covering both numeric ID and full URL formats. The tool description adds no additional meaning about the parameter itself – it only restates that it retrieves "one AliExpress product." With 100% schema coverage, baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: "Retrieve the record of one AliExpress product." It also positions itself relative to the sibling by stating "Use after `search_aliexpress` surfaces something worth a closer look," which clearly distinguishes this detail-lookup tool from the search tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to use the tool: "Use after `search_aliexpress` surfaces something worth a closer look." This names the sibling and gives an explicit trigger condition, leaving no ambiguity about workflow ordering. It also instructs the agent to check `source` and `partial` fields before describing the result, which is practical guidance for correct use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_aliexpressSearch AliexpressA

Search AliExpress product listings by keyword.

Returns a list of products — id, title, sale price (and original price / discount), star rating, orders-sold text, thumbnail image and product URL. Prices and titles follow the configured market (Germany / EUR by default). Pass a product's id to get_aliexpress_product for full details.

ParametersJSON Schema
NameRequiredDescriptionDefault
pageNoResult page (1-indexed), ~60 items per page.
sortNoSort order: 'orders' (best-selling), 'price_asc' (cheapest first), 'price_desc' (most expensive first), 'newest'. Omit for AliExpress's default relevance ranking.
limitNoMaximum results to return (one page holds ~60)
queryYesSearch keywords, e.g. 'usb c kabel' or 'anker powerbank'
max_priceNoMaximum price filter, in EUR.
min_priceNoMinimum price filter, in EUR.
max_resultsNoDeprecated alias for `limit`; prefer `limit`.

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the behavioral burden. It specifies the exact output fields, explains that prices and titles follow the configured market (Germany/EUR default), and implies a read-only search operation. It doesn't cover error or no-results behavior, but for a listing search the disclosed behavior is solid.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Four compact sentences cover the action, return shape, market configuration, and next-step routing. Every sentence earns its place, and the most decision-relevant facts are front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Between the description and the complete input schema, an agent knows what results look like, how paging and filters work, and when to escalate to the sibling. The only small weakness is that some behavior, such as pagination defaults and the deprecated `max_results` alias, is left entirely to the schema rather than reinforced in the description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds useful market context that affects how price parameters are interpreted, but it does not add meaning to page, sort, limit, or query beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Search AliExpress product listings by keyword.' It then enumerates the return fields, distinguishing this list-level tool from get_aliexpress_product, which is referenced for full product details.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly scopes the tool to keyword-based listing searches and explicitly routes deeper needs to get_aliexpress_product ('Pass a product's `id` to `get_aliexpress_product` for full details'). It does not list when not to use this tool, but the alternative is named and the decision boundary is obvious.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv0.3.2
    • First observedget_aliexpress_product
    • First observedsearch_aliexpress
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.3/5.0

Scored across 2 tools

Disambiguation5/5

The two tools have clearly distinct purposes: one searches for product listings while the other retrieves details for a specific product. Their descriptions explicitly cross-reference each other, leaving no ambiguity about when to use which.

Naming Consistency4/5

Both names use a consistent snake_case, action-first style: search_aliexpress and get_aliexpress_product. The minor deviation is that one name lacks a noun object, but the pattern is still predictable and readable.

Tool Count3/5

Two tools is a minimal but reasonable surface for a read-only product search and detail lookup server. It feels thin compared to more feature-complete e-commerce servers, but each tool earns its place in the core workflow.

Completeness4/5

The search-then-get flow covers the main user journey without dead ends. Pagination, category browsing, or review listing could be useful additions, but they are not essential gaps for the stated purpose of searching and inspecting products.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • MCP Shop Server

    johan-perso
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables AI models to find the best online deals by browsing and interacting with multiple shopping platforms like Amazon and eBay across various regions. It uses Playwright to automate searches and retrieve product information from compatible e-commerce and deal-tracking websites.
    7 npm
    3
    MIT

  • fetchaller

    Averyy
    A
    license
    A
    quality
    B
    maintenance
    Enables fetching any website without permission prompts, including automatic bot challenge bypass, with built-in web search, Reddit, marketplace, realtor, AliExpress, and Alibaba tools.
    12
    14
    MIT