Guía de instalación de Mercury Agent

Mercury Agent es un agente de prospección gratis y de código abierto, creado por Altamar. Encuentra negocios que encajan con tu cliente, busca un motivo real para escribirle a cada uno, redacta correos en frío cortos, los envía desde tus propios buzones y te prepara las respuestas. Su trabajo de IA pasa por Claude Code, así que cuenta contra el plan Claude Pro o Max que ya pagas, sin una factura por tokens. No se envía nada hasta que tú lo apruebas.

Esta guía te lleva de cero a tu primer correo aprobado. Calcula unos 30 minutos, casi todos en el buzón. La documentación completa está en el repositorio de Mercury (en inglés).

#Antes de empezar

Necesitas cuatro cosas:

• Python 3.11 o más reciente. En Mac, el python3 que viene instalado suele ser 3.9. Si es tu caso, instala uno más nuevo con Homebrew.
• Claude Code con sesión iniciada en un plan Pro o Max. Instálalo y ejecuta claude login una vez.
• Un buzón en un dominio aparte. Compra un segundo dominio (por ejemplo getyourcompany.com además de yourcompany.com) y ponle un buzón de Google Workspace, unos $7 al mes. Si el cold email llega a dañar la reputación de ese dominio, tu correo real no se toca.
• Una clave de verificación de correos. Reoon da 600 verificaciones gratis al mes. Sin un verificador, Mercury no puede confirmar direcciones, y nunca envía a una dirección que no ha confirmado.

La forma fácil: cuando hayas clonado Mercury (paso 1), ejecuta claude dentro de su carpeta y dile “set up Mercury for me”. Claude Code lee las instrucciones que trae el proyecto y te guía por el resto de esta guía.

#1. Instala

01git clone https://github.com/altamar-dev/MERCURY-AGENT.git mercury-agent02cd mercury-agent03python3 -m venv .venv04source .venv/bin/activate05pip install -e .

Esto instala el comando mercury. Vuelve a ejecutar source .venv/bin/activate en cada ventana nueva de la terminal.

#2. Conecta tu buzón

01cp .env.example .env

Abre .env y completa dos cosas: un proveedor de correo y tu clave del verificador (REOON_API_KEY). Cada línea del archivo dice de dónde sacar su valor.

Gmail o Google Workspace (recomendado):

1. En Google Cloud Console, crea un proyecto y activa la API de Gmail.
2. Configura la pantalla de consentimiento OAuth (interna o de prueba) y crea un cliente OAuth de tipo “App de escritorio”.
3. Pega su ID y su secreto en .env como GMAIL_CLIENT_ID y GMAIL_CLIENT_SECRET.
4. Inicia sesión una vez en el navegador y prueba la conexión:

01mercury gmail auth02mercury gmail test

Cualquier otro buzón: completa SMTP_HOST, SMTP_PORT, SMTP_USERNAME, SMTP_PASSWORD e IMAP_HOST, y luego ejecuta mercury mail test.

#3. Enséñale lo que vendes

01mercury train https://tu-empresa.com

Mercury lee tu sitio web y guarda su configuración en mercury.local.yaml. Abre ese archivo y corrige tres cosas antes de seguir. Son las que más confunden:

01persona:02  name: "Tu Nombre"                        # el entrenamiento escribe "Mercury"03  email: "tu@getyourcompany.com"           # tu buzón de envío04 05channels:06  email:07    provider: "gmail"                      # el entrenamiento escribe "instantly"; usa gmail o smtp08    require_approval: true                 # déjalo activado09 10compliance:11  postal_address: "Calle 1 #23, Ciudad, País"   # no se envía nada hasta que esté puesta

La dirección postal va en el pie de cada correo, junto a una línea para darse de baja, como exige la ley de cold email. Mercury retiene toda la bandeja de salida hasta que la completes.

#4. Elige qué busca Mercury y encuentra negocios

Mercury te propone los datos que puede reunir de cada negocio: reseñas, ofertas de empleo, el nombre del dueño, si hacen anuncios y más. Solo reúne los que tú confirmas. Empieza con todo lo que no cuesta nada:

01mercury signals --confirm free02mercury discover --estimate03mercury discover

--estimate muestra cuánto costaría una búsqueda sin ejecutarla. La fuente por defecto, OpenStreetMap, es gratis y no necesita cuenta. Tiene poca cobertura de negocios sin local a la calle, así que mercury discover --providers te muestra las fuentes de pago y sus precios si necesitas más. Toda búsqueda de pago se detiene en un tope de gasto.

#5. Abre el panel y aprueba tus primeros correos

01mercury dashboard

Abre http://127.0.0.1:5555. Luego arranca Mercury en otra terminal (activa el venv ahí también):

01mercury run

Cada 15 minutos verifica direcciones, escribe una secuencia de tres correos para cada contacto confirmado y los deja en la bandeja de salida (Outbox). No sale nada hasta que lo apruebas. En el Outbox, usa J y K para moverte entre borradores, corrige cualquier palabra ahí mismo y pulsa A para aprobar. Lee los diez primeros con calma. Si no dan en el clavo, dile a Mercury qué cambiar y reescribe el borrador.

#Primera semana: ve despacio

• Cinco correos al día. Los buzones nuevos empiezan con 5 al día y suben 5 por semana. No lo aumentes. Enviar demasiado desde un buzón nuevo es la forma más rápida de acabar en spam.
• Revisa la configuración de tu correo. La pestaña Mailboxes revisa los registros SPF, DKIM y DMARC de tu dominio. Arregla lo que salga en rojo antes de enviar.
• Vigila los rebotes. Con más de 3% de rebotes, el buzón se queda en el volumen de ayer, y con más de 5% se pausa hasta que lo reanudes. Si pasa, detente y revisa tu lista antes de enviar más.
• Responde a las respuestas. Mercury clasifica las respuestas y te prepara una contestación para cada una, pero la apruebas tú, igual que el primer correo. Quien pida que no le escribas más no vuelve a recibir nada.
• Parada de emergencia: mercury sending pause detiene al instante todo el correo saliente.

Cumplir la ley de cold email (CAN-SPAM en EE. UU., el RGPD en Europa) es tu responsabilidad como remitente. Mercury añade el pie y respeta las bajas, pero tú decides a quién escribes.

#Si algo falla

• No se envía nada: revisa compliance.postal_address y channels.email.provider en mercury.local.yaml, y confirma que los correos están aprobados en el Outbox.
• Todas las direcciones dicen “guess”: añade una clave de verificador en .env. Las direcciones adivinadas nunca se envían.
• mercury: command not found: activa el venv con source .venv/bin/activate.
• El descubrimiento no arranca: confirma al menos una señal con mercury signals --confirm free.

¿Atascado en otra cosa? Responde al mensaje de Instagram que te envió esta guía, o abre un issue en GitHub.