<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 · Español · Português

<br/>

</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 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 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 (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 (npm run build recompila el binario para tu equipo).

💻 Claude Code — un comando

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:

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 o 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):

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

Verifica que quedó conectado:

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 arriba.

Opción B — Configuración manual

1. Abre (o crea) el archivo de configuración de Claude Desktop en macOS:

   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):

   {
     "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)
• 🚙 Buscar Golf GTI en Providencia (últimos 7 días)

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:

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:

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.