<div align="center">

# 🛒 Facebook Marketplace MCP

Busca en **Facebook Marketplace** directamente desde Claude (Claude Code o Claude Desktop).
Sin navegador: reutiliza tu sesión de Facebook ya iniciada en Chrome.

[English](README.en.md) · **Español** · [Português](README.pt.md)

<br/>

[![Instalar en Claude Desktop](https://img.shields.io/badge/⬇%20Instalar%20en-Claude%20Desktop-D97757?style=for-the-badge&logo=anthropic&logoColor=white)](https://github.com/fjvalencian/marketplace-mcp/releases/latest/download/facebook-marketplace-mcp.mcpb)
[![Añadir a Claude Code](https://img.shields.io/badge/+%20Añadir%20a-Claude%20Code-2D2A26?style=for-the-badge&logo=anthropic&logoColor=white)](#-instalar-en-claude-code)

</div>

---

## ⚠️ Léelo antes de instalar (transparencia y seguridad)

Este proyecto es de código abierto y queremos ser **100% transparentes** sobre lo que hace:

- 🍪 **Lee las cookies de tu sesión de Facebook desde Chrome.** Para hacerse pasar por ti ante Facebook, el servidor copia la base de datos de cookies de Chrome y la **descifra usando la clave guardada en el Llavero (Keychain) de macOS**. La primera vez, macOS te pedirá tu contraseña para autorizar ese acceso. Las cookies se usan solo en tu equipo, para hablar con `facebook.com`; **no se envían a ningún tercero**.
- 📜 **Automatizar Facebook viola sus Términos de Servicio.** Facebook puede pedir CAPTCHAs, limitar o **bloquear la cuenta** que uses.
- 🧑‍🔧 **Recomendación fuerte: usa una cuenta secundaria de Facebook, NO tu cuenta principal.** Crea una cuenta aparte (idealmente en un **perfil de Chrome distinto**) e inicia sesión ahí solo para esto. Así, si Facebook marca o bloquea la cuenta, no pierdes tu cuenta personal. Configura ese perfil con la variable `CHROME_PROFILE` (ver más abajo).
- 🐢 **Uso responsable.** El servidor se auto-limita a pocas solicitudes por minuto para no llamar la atención. No subas ese límite de forma agresiva.
- 🔍 **Solo lectura.** Busca y lee publicaciones; no publica, no envía mensajes, no modifica nada en tu cuenta.

Al usar este software aceptas estos riesgos bajo tu propia responsabilidad.

---

## 🧠 ¿Cómo funciona? (en simple)

1. **Toma tu sesión:** copia las cookies de Facebook desde Chrome y las descifra con la clave del Llavero de macOS.
2. **Consigue los tokens:** abre `facebook.com/marketplace/` (como una página normal) y extrae los tokens de seguridad (`fb_dtsg`, `lsd`, etc.) que Facebook exige.
3. **Habla el protocolo de Facebook:** hace las mismas llamadas `POST /api/graphql/` que hace el sitio web de Facebook, usando identificadores de consulta (`doc_id`) y tu sesión.
4. **Te devuelve resultados limpios:** título, precio, ubicación, vendedor, fecha, foto y enlace de cada publicación.

Es la misma idea que [pypush](https://github.com/JJTech0130/pypush) para iMessage: protocolo directo, sin navegador en tiempo de ejecución.

---

## ✅ Requisitos

- **macOS** (la extracción de cookies usa el Llavero de Apple).
- **Google Chrome** con una sesión de Facebook **iniciada** (idealmente una cuenta secundaria).
- Para el método manual: **Node.js 20 o superior** (`node --version`). Instálalo desde [nodejs.org](https://nodejs.org/) o con `brew install node`. _(La extensión `.mcpb` de Claude Desktop no necesita que instales Node.)_

---

## ⚡ Instalación rápida

### 🖥️ Claude Desktop — un clic

1. **[⬇ Descarga la extensión `.mcpb`](https://github.com/fjvalencian/marketplace-mcp/releases/latest/download/facebook-marketplace-mcp.mcpb)** (botón de arriba).
2. **Doble clic** en el archivo descargado (o arrástralo a Claude Desktop → menú ☰ → **Settings → Extensions**).
3. Revisa los detalles y pulsa **Install**. Ajusta si quieres el perfil de Chrome y el límite de solicitudes.
4. ¡Listo! Pídele a Claude que busque algo en Marketplace.

> La extensión precompilada es para **macOS con chip Apple Silicon (M1/M2/M3…)**. Si tienes un Mac Intel, usa el [método manual](#-instalar-en-claude-code) (`npm run build` recompila el binario para tu equipo).

### 💻 Claude Code — un comando

```bash
git clone https://github.com/fjvalencian/marketplace-mcp.git && cd marketplace-mcp && npm install && npm run build
claude mcp add facebook-marketplace --scope user -- node "$(pwd)/dist/index.js"
```

Detalle paso a paso más abajo. 👇

---

## 🐣 Guía paso a paso "para dummies"

> Sigue esto tal cual, línea por línea. No necesitas saber programar.

### 1) Abre la Terminal
En Spotlight (⌘ + Espacio) escribe **"Terminal"** y ábrela.

### 2) Descarga el proyecto
Copia y pega estos comandos, uno a uno, y presiona Enter después de cada uno:

```bash
git clone https://github.com/fjvalencian/marketplace-mcp.git
cd marketplace-mcp
npm install
npm run build
```

Si todo salió bien, se creó una carpeta `dist/` con el servidor compilado.

### 3) Averigua la ruta completa del proyecto
Ejecuta `pwd` y copia lo que aparece (por ejemplo `/Users/tunombre/marketplace-mcp`). La ruta al servidor será eso **+ `/dist/index.js`**.

### 4) Inicia sesión en Facebook (cuenta secundaria) en Chrome
Abre **Google Chrome** e inicia sesión en la cuenta de Facebook que vas a usar. Déjala con sesión abierta.

### 5) Conéctalo a Claude
Sigue **[Instalar en Claude Code](#-instalar-en-claude-code)** o **[Instalar en Claude Desktop](#-instalar-en-claude-desktop)**. Reinicia la app después.

### 6) Pruébalo
Escríbele a Claude: *"Busca un BMW E30 en Santiago de Chile, entre 2 y 8 millones, ordenado por precio."*

La **primera vez**, macOS mostrará una ventana pidiendo tu contraseña para acceder al Llavero ("Chrome Safe Storage"). Escríbela y dale **Permitir siempre**. ¡Listo!

---

## 💻 Instalar en Claude Code

Ejecuta esto reemplazando la ruta por la tuya (paso 3):

```bash
claude mcp add facebook-marketplace --scope user -- node /RUTA/COMPLETA/marketplace-mcp/dist/index.js
```

Verifica que quedó conectado:

```bash
claude mcp list
```

Debe aparecer `facebook-marketplace ... ✔ Connected`. Reinicia Claude Code para que las herramientas estén disponibles.

---

## 🖥️ Instalar en Claude Desktop

### Opción A — Extensión `.mcpb` (recomendada, un clic)
Ver [Instalación rápida](#️-claude-desktop--un-clic) arriba.

### Opción B — Configuración manual
1. Abre (o crea) el archivo de configuración de Claude Desktop en macOS:

   ```bash
   open -e ~/Library/Application\ Support/Claude/claude_desktop_config.json
   ```

2. Agrega el bloque `"facebook-marketplace"` (reemplaza la **ruta** por la tuya del paso 3):

   ```json
   {
     "mcpServers": {
       "facebook-marketplace": {
         "command": "node",
         "args": ["/RUTA/COMPLETA/marketplace-mcp/dist/index.js"],
         "env": { "CHROME_PROFILE": "Default" }
       }
     }
   }
   ```

3. Guarda y **cierra y vuelve a abrir Claude Desktop** por completo.

---

## 🔁 Rutinas y búsquedas rápidas

¿Quieres un "botón" que abra Claude Desktop y lance una búsqueda al instante? Usa los enlaces `claude://`. Al hacer clic, se abre Claude Desktop con el mensaje ya escrito (necesitas la extensión instalada).

> 📌 Reemplaza el prompt por lo que busques. Ejemplos listos (haz clic):

- 🚗 [Buscar BMW E30 en Santiago (2–8M, por precio)](claude://claude.ai/new?q=Busca%20un%20BMW%20E30%20en%20Santiago%20de%20Chile%20entre%202.000.000%20y%208.000.000%20CLP%2C%20ordenado%20por%20precio%2C%20usando%20facebook-marketplace)
- 🚙 [Buscar Golf GTI en Providencia (últimos 7 días)](claude://claude.ai/new?q=Busca%20un%20Volkswagen%20Golf%20GTI%20en%20Providencia%2C%20Chile%2C%20publicados%20en%20los%20%C3%BAltimos%207%20d%C3%ADas%2C%20usando%20facebook-marketplace)

Para crear tu propio botón, arma un enlace así (codifica el texto para URL):

```
claude://claude.ai/new?q=TU_BUSQUEDA_AQUI
```

### Convertirlo en una rutina recurrente (que corra sola)

No existe un enlace que **cree** la rutina automáticamente, pero configurarla toma 30 segundos:

1. En **Claude Desktop** abre la barra lateral → **Routines** → **New routine**.
2. Pega un prompt como: *"Revisa facebook-marketplace por BMW E30 nuevos en Santiago bajo 8 millones y resúmelos."*
3. Elige la frecuencia (diaria, semanal…) y guarda.

> 💡 Alternativa dentro del propio MCP: usa `monitor_search` para guardar una búsqueda y `check_monitors` para ver solo lo nuevo desde la última vez. Perfecto para combinar con una rutina.

---

## 🛠️ Herramientas disponibles

### `search_listings`
Busca publicaciones por texto, ubicación y filtros.

| Parámetro | Tipo | Requerido | Descripción |
|-----------|------|-----------|-------------|
| `query` | string | sí | Texto a buscar (ej: `"BMW E30"`) |
| `latitude` | number | sí | Latitud del centro de búsqueda |
| `longitude` | number | sí | Longitud del centro de búsqueda |
| `radius_km` | number | no | Radio en km (por defecto: 50) |
| `min_price` | number | no | Precio mínimo, en pesos/dólares (la unidad de la moneda) |
| `max_price` | number | no | Precio máximo, en pesos/dólares |
| `condition` | string[] | no | Estado: `new`, `used_like_new`, `used_good`, `used_fair` |
| `days_since_listed` | number | no | Solo publicaciones de los últimos N días |
| `sort_by` | string | no | `best_match` (def.), `price_asc`, `price_desc`, `date_desc` |
| `category` | string | no | ID de categoría |
| `cursor` | string | no | Cursor para traer la página siguiente (paginación) |
| `limit` | number | no | Máximo de resultados (por defecto: 20) |

> 💰 **Sobre los precios:** escribe `min_price`/`max_price` en la unidad normal de la moneda (ej. `2000000` para 2 millones de pesos). El servidor hace la conversión que Facebook espera internamente. Muchos vendedores ponen precios falsos ($0, $123, $12.345.678); esos aparecen marcados con **⚠️ precio dudoso**.

### `get_listing`
Devuelve datos de una publicación por su `listing_id`. Nota: Facebook no expone la descripción completa de un aviso vía API sin navegador, así que esta herramienta puede devolver solo el enlace directo para abrirlo. La búsqueda ya entrega título, precio, ubicación, vendedor y foto.

### `search_location`
Convierte el nombre de una ciudad/comuna en coordenadas para usar en `search_listings`. Parámetro: `query` (ej: `"Santiago, Chile"`, `"Providencia"`).

### Monitores (seguimiento de búsquedas)
- `monitor_search` — guarda una búsqueda como monitor.
- `check_monitors` — revisa si hay publicaciones nuevas desde la última vez.
- `list_monitors` — lista los monitores guardados.
- `delete_monitor` — elimina un monitor.

---

## 💬 Ejemplos de uso (lenguaje natural en Claude)

- *"Busca un BMW E30 en Santiago de Chile, entre 2 y 8 millones, ordenado por precio."*
- *"Muéstrame Golf GTI en Providencia publicados en los últimos 7 días."*
- *"Crea un monitor llamado 'e30' para BMW E30 en Santiago y avísame de lo nuevo."*
- *"Dame el detalle de la publicación con id 1726115965212924."*

---

## ⚙️ Variables de entorno

| Variable | Por defecto | Descripción |
|----------|-------------|-------------|
| `CHROME_PROFILE` | `Default` | Nombre de la carpeta del perfil de Chrome del que se leen las cookies |
| `FB_MAX_RPM` | `3` | Máximo de solicitudes por minuto (sube con cuidado; más = más riesgo) |

### Perfiles de Chrome
Si tu cuenta secundaria está en otro perfil de Chrome, indica su carpeta en `CHROME_PROFILE`. Los perfiles se guardan en `~/Library/Application Support/Google/Chrome/`. El primero es `Default`; los siguientes son `Profile 1`, `Profile 2`, etc.

---

## 📦 Generar tu propia extensión `.mcpb`

Si modificas el código o usas un Mac Intel, regenera el bundle:

```bash
npm install
npm run build
npm prune --omit=dev          # deja solo dependencias de producción (bundle liviano)
npx @anthropic-ai/mcpb pack   # genera facebook-marketplace-mcp.mcpb
npm install                   # restaura dependencias para futuros builds
```

Luego instala el `.mcpb` en Claude Desktop con doble clic.

---

## 🔄 Cuando Facebook cambia sus `doc_id`

Facebook rota sus identificadores de consulta (`doc_id`) en cada despliegue. Si las búsquedas dejan de funcionar de golpe, recaptúralos:

```bash
npm install -D playwright
npx playwright install chromium
npm run capture-queries
```

Esto abre un navegador, navega por Marketplace y captura los IDs actuales. Actualiza los valores en `src/facebook/queries.ts` y vuelve a compilar con `npm run build`.

---

## 🚫 Limitaciones

- Solo **macOS** (por el descifrado con el Llavero).
- Requiere **Chrome con sesión de Facebook** activa.
- **Frágil:** los `doc_id` cambian cuando Facebook actualiza su sitio.
- **Con límite de tasa:** un uso agresivo puede gatillar CAPTCHAs o bloqueos.
- **Solo lectura:** no mensajea ni publica.

---

## ✨ Características

Funcionalidades del servidor, todas verificadas con búsquedas reales:

- **🔄 Reintento de sesión automático.** Si la sesión expira (401/403 o token rotado), el servidor reinicializa y reintenta la búsqueda de forma transparente.
- **💰 Filtro de precio configurable.** El factor de conversión de precios es explícito y está verificado para pesos chilenos (`price_scale`, por defecto 100).
- **📄 Paginación.** `search_listings` acepta un `cursor` y devuelve el cursor de la página siguiente.
- **🔎 Filtros y orden.** `condition`, `days_since_listed` y `sort_by` (por precio o fecha).
- **🧾 Resultados ricos.** Incluye fecha de publicación, foto, `id` para usar en `get_listing`, y marca los precios claramente falsos con ⚠️.
- **🚦 Rate limit configurable** por `FB_MAX_RPM`.
- **🛡️ Manejo de errores claro.** Distingue "sesión expirada" de otros errores en lugar de fallar en silencio.

---

## 📄 Licencia

Uso educativo y personal. Respeta los Términos de Servicio de Facebook y las leyes aplicables. Los autores y contribuyentes no se hacen responsables del uso indebido ni de bloqueos de cuenta.