# 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

```bash
# 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`:

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

### OpenCode

Add to `.opencode.json`:

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

```bash
# 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.