letgo-mcp

A Model Context Protocol (MCP) server for searching listings, viewing listing details, and applying filters on Letgo.com. It uses Playwright browser automation to bypass Letgo's Akamai anti-bot protection and accesses data in a way that closely mimics real user behavior.

Features

• City and district-level location setting
• Autocomplete search suggestions
• Listing search (with price range, sorting, category, and pagination support)
• Individual listing details (description, seller info, images)
• Infinite scroll — automatically clicks "Load More" to collect all results
• Session refresh against Akamai anti-bot protection
• Network request debugging via interception
• No API keys required

Requirements

• Node.js v22 or higher
• npm (ships with Node.js)
• Playwright browser engine (downloaded automatically during setup)

Installation

# Clone the repository
git clone <repo-url>
cd letgo-mcp

# Install dependencies
npm install

# Download the Playwright browser
npx playwright install chromium

# Build the project
npm run build

After building, executable JavaScript files will be available under the dist/ directory.

MCP Configuration

letgo-mcp runs as a stdio MCP server. Add it to any MCP-compatible client (Claude Desktop, OpenCode, etc.) as follows:

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "letgo-mcp": {
      "command": "node",
      "args": ["/path/to/letgo-mcp/dist/index.js"]
    }
  }
}

OpenCode

Add to .opencode.json:

{
  "mcpServers": {
    "letgo-mcp": {
      "command": "node",
      "args": ["/path/to/letgo-mcp/dist/index.js"]
    }
  }
}

Replace the path with the full path to your project.

Usage

The tools must be called in the correct order. Follow this flow:

1. Set location — Use letgo_set_location to set the target city for searches. This must be called before every search.
2. Search — Use letgo_search_listings to search listings. Optionally, use letgo_search_suggestions to get autocomplete suggestions.
3. Details — Use letgo_get_listing_details to view the full details of a listing.
4. Maintenance — If session issues arise, call letgo_refresh_session. Use letgo_debug_network to inspect network requests.

Running from the Command Line

# Build
npm run build

# Run (as stdio MCP server)
npm start

# Development mode (build + run)
npm run dev

Tools Reference

Tool	Description	Parameters
letgo_set_location	Sets the search location. Must be called before any search.	city (string, required) — City name, district (string, optional) — District name
letgo_search_suggestions	Returns autocomplete suggestions for a given query.	query (string, required) — Search text
letgo_search_listings	Searches listings on Letgo. Supports filtering, sorting, and pagination.	query (string, required), page (number, default: 1), minPrice (number), maxPrice (number), sortBy (enum: price_asc, price_desc, date_desc, date_asc, distance), categoryId (string)
letgo_get_listing_details	Returns full details of a listing including title, description, seller info, images, and attributes.	listing_id (string, required) — Listing ID
letgo_refresh_session	Refreshes Akamai anti-bot cookies. Use when search results return empty or errors occur.	No parameters
letgo_debug_network	Navigates to a search page and captures all API/network calls made by the page. Useful for discovering which endpoints are used.	query (string, default: "iphone")

Architecture

The project consists of two main components:

Session Management (session.ts): Spawns a Chromium browser instance via Playwright. The browser runs in headless: false (visible) mode. Several measures are taken to bypass Letgo's Akamai bot detection:

• Realistic user agent and viewport configuration
• Hiding the navigator.webdriver flag
• Turkish language and Istanbul timezone settings
• API calls are made using page.evaluate(fetch) so the browser's existing cookies and session data are used
• If the browser crashes or an error occurs, it is automatically restarted

API Client (api-client.ts): Accesses Letgo's internal API endpoints (/api/suggestions) and listing pages through the DOM. Search results are collected via DOM scraping: the "Load More" button is automatically clicked to simulate infinite scroll, then listing cards are extracted using the a[href*="/item/"] selector.

Tool Handler (index.ts): Defines 6 tools via the MCP SDK. Routes incoming requests to functions in api-client.ts and session.ts. Input and output schemas are defined according to MCP standards.

Data Flow

MCP Client -> stdio -> index.ts (handler) -> 
  api-client.ts -> session.ts (Playwright) -> Letgo.com

All HTTP requests are made from within the browser context, ensuring Letgo's session and cookie mechanisms work seamlessly.

Important Notes

• No API key required. It works through Letgo's own web interface — no official API is used.
• Browser runs visible (headless: false). Letgo's Akamai anti-bot may block headless browsers, so the browser window stays open.
• Location is required. No search can be performed without calling letgo_set_location. City names must be entered with Turkish characters (e.g., "İzmir", "İstanbul", "Ankara").
• Session durations are limited. Letgo's Akamai cookies remain valid for a limited time. Use letgo_refresh_session to renew the session.
• Rate limiting. Sending too many requests in quick succession may cause Letgo to temporarily restrict access. Session refresh usually resolves this.
• DOM scraping. Search results are extracted from Letgo's HTML DOM. If Letgo changes their UI, the scraping selectors may need to be updated.
• Turkey only. Designed for the Letgo Turkey platform. Location data covers Turkish cities.