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

Related MCP server: OLX MCP Server

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

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.