ProspectMCP

Servidor MCP + API REST para prospectar negocios de Google Maps / Google Business:

• 🔍 Búsqueda de negocios por texto libre ("pizzerías en Palermo, Buenos Aires").
• 🌐 Filtro con/sin página web — ideal para encontrar negocios a los que venderles una web.
• ⭐ Extracción de reviews — hasta 5 con la API oficial de Google, o todas (paginadas) si configurás SerpAPI.
• 📱 Detección de redes sociales — si el negocio tiene web, se detectan sus links a Facebook, Instagram, X, LinkedIn, TikTok, YouTube y WhatsApp.
• 🤖 Generador de prompt para Claude Code — arma un prompt listo para que Claude Code construya la landing page del negocio basada en sus datos reales, sus mejores reviews y sus redes.

Arquitectura

src/
├── providers/
│   ├── googlePlaces.ts   # Google Places API (New): búsqueda, ficha, reviews (máx. 5)
│   └── serpapi.ts        # SerpAPI (opcional): todas las reviews, paginadas
├── services/
│   ├── prospectService.ts # Lógica central: búsqueda + filtros, reviews, perfiles
│   ├── socialLinks.ts     # Detección de redes sociales en la web del negocio
│   └── promptBuilder.ts   # Prompt de landing page para Claude Code
├── mcp/server.ts          # Servidor MCP (stdio) para Claude
└── api/server.ts          # API REST con API keys (base para comercializar)

Por qué APIs y no scraping directo: Google bloquea agresivamente el scraping de Maps (captchas, bans de IP) y viola sus términos de servicio. Este proyecto usa la Places API (New) oficial y, para el histórico completo de reviews, SerpAPI — un servicio de pago que resuelve ese problema de forma estable. El diseño con providers permite enchufar otras fuentes más adelante.

Configuración

1. Cloná el repo e instalá dependencias:

   npm install
   npm run build
   

2. Copiá .env.example a .env y completá:

   Variable	Requerida	Descripción
   GOOGLE_PLACES_API_KEY	✅	API key de Google Cloud con Places API (New) habilitada
   SERPAPI_KEY	opcional	Para extraer todas las reviews (sin ella: máx. 5)
   API_KEYS	opcional	Keys válidas para la API REST, separadas por coma
   PORT	opcional	Puerto de la API REST (default 3000)
   DEFAULT_LANGUAGE / DEFAULT_REGION	opcional	Defaults es / AR

Hostearlo como conector remoto (Render)

El servidor MCP tiene dos transportes:

• stdio (dist/mcp/server.js) — para correrlo localmente en tu máquina.
• Streamable HTTP (dist/mcp/httpServer.js) — para hostearlo y que cualquiera lo use con un link.

Para deployar en Render:

1. Pusheá el repo a GitHub y en Render elegí New → Blueprint apuntando al repo (detecta render.yaml solo).
2. Cargá GOOGLE_PLACES_API_KEY (y opcionalmente SERPAPI_KEY y MCP_AUTH_TOKENS) en el dashboard.
3. Tu conector queda en https://<tu-app>.onrender.com/mcp.

Con esa URL, cualquier persona lo agrega:

• Claude web/desktop: Configuración → Conectores → Agregar conector personalizado → pegar la URL.
• Claude Code: claude mcp add --transport http prospectmcp https://<tu-app>.onrender.com/mcp

Seguridad/costos: cada búsqueda consume TU cuota de Google Places y SerpAPI. Si el conector va a ser público, definí MCP_AUTH_TOKENS (tokens separados por coma) y repartí un token por cliente; los clientes lo mandan como header Authorization: Bearer <token>. Ojo: el plan free de Render duerme el servicio tras 15 min de inactividad (el primer request tarda ~30-60s en despertar); para uso comercial conviene el plan Starter.

Uso como servidor MCP local (Claude Code / Claude Desktop)

Agregalo a Claude Code:

claude mcp add prospectmcp \
  --env GOOGLE_PLACES_API_KEY=TU_KEY \
  --env SERPAPI_KEY=TU_KEY_OPCIONAL \
  -- node /ruta/a/ProspectMCP/dist/mcp/server.js

O en claude_desktop_config.json / .mcp.json:

{
  "mcpServers": {
    "prospectmcp": {
      "command": "node",
      "args": ["/ruta/a/ProspectMCP/dist/mcp/server.js"],
      "env": {
        "GOOGLE_PLACES_API_KEY": "TU_KEY",
        "SERPAPI_KEY": "TU_KEY_OPCIONAL"
      }
    }
  }
}

Herramientas MCP disponibles

Herramienta	Qué hace
search_businesses	Busca negocios con filtro with_website / without_website / any y rating mínimo
get_business	Ficha completa de un negocio por place_id
get_reviews	Extrae reviews (todas con SerpAPI; hasta 5 sin ella)
get_business_profile	Ficha + reviews + redes sociales en una sola llamada
generate_website_prompt	Prompt listo para Claude Code que arma la landing del negocio

Ejemplo de flujo en Claude:

"Buscá gimnasios en Rosario que no tengan página web y rating mayor a 4. Del más prometedor, traeme todas las reviews y generame el prompt para armarle la página."

Uso como API REST

npm run start:api

Endpoint	Descripción
GET /health	Estado del servicio
GET /search?query=...&website_filter=without_website&min_rating=4	Búsqueda con filtros
GET /business/:placeId	Ficha del negocio
GET /business/:placeId/reviews?max_reviews=200	Reviews
GET /business/:placeId/profile	Ficha + reviews + redes
POST /business/:placeId/website-prompt	Genera el prompt para Claude Code (body: { "language": "es", "style_notes": "..." })

Con API_KEYS configurado, todas las rutas (salvo /health) exigen el header X-API-Key.

curl -H "X-API-Key: mi-key" \
  "http://localhost:3000/search?query=peluquerías%20en%20Córdoba&website_filter=without_website"

Roadmap (comercialización)

• [ ] Panel web del proyecto: búsquedas guardadas, listas de prospectos, exportación CSV.
• [ ] Botón "Generar prompt para Claude Code" por negocio dentro del panel (el endpoint ya existe).
• [ ] Planes y facturación por API key (rate limiting + cuotas).
• [ ] Más providers de reviews y enriquecimiento (email finder, etc.).

Licencia

MIT