Job Finder

Encuentra trabajos para cualquier oficio, en cualquier país — a partir de una frase, o de tu CV — y los clasifica según tu probabilidad realista de ser preseleccionado.

jobfinder daily --query "electrician jobs in Dubai"

Recibes una hoja de cálculo en tu escritorio, ordenada de mejor a peor. Se abre cuando termina la ejecución.

Todo se ejecuta en tu máquina. Tu CV nunca sale de ella, salvo como texto enviado a la API de Anthropic con tu propia clave, y tus términos de búsqueda van a los portales de empleo que hayas habilitado — exactamente como si los escribieras en esos sitios.

Inicio rápido

Cuatro pasos. Tarda unos cinco minutos.

1. Instalar

git clone https://github.com/MajidAli2006/jobfinder.git
cd jobfinder
python3 -m venv .venv
.venv/bin/pip install -e ".[all]"

2. Obtener una clave de API

Ve a console.anthropic.com/settings/keys, inicia sesión, haz clic en Create Key y cópiala. Empieza con sk-ant-.

Esta es la única clave que la herramienta realmente necesita.

3. Pon la clave en un archivo llamado .env

cp .env.example .env

Abre .env en cualquier editor de texto y pega tu clave después del =, sin comillas y sin espacios:

ANTHROPIC_API_KEY=sk-ant-your-key-here

Guárdalo. .env está en git-ignore, así que tu clave nunca se confirma.

4. Comprueba que funciona y luego busca

.venv/bin/jobfinder setup
.venv/bin/jobfinder daily --query "warehouse jobs in Leeds"

Consejo: ejecuta source .venv/bin/activate una vez y puedes omitir el prefijo .venv/bin/ durante el resto de tu sesión de terminal.

Related MCP server: JobSpy MCP Server

Úsalo desde Claude (MCP)

Esta herramienta también es un servidor MCP, así que puedes simplemente pedirle a Claude que busque por ti.

Claude Code — un comando:

claude mcp add --scope user jobfinder -- /full/path/to/jobFinder/.venv/bin/jobfinder-mcp

Reemplaza /full/path/to/jobFinder con el lugar donde lo hayas clonado. Ejecuta pwd dentro de la carpeta para obtenerlo.

Claude Desktop — abre claude_desktop_config.json y añade:

{
  "mcpServers": {
    "jobfinder": {
      "command": "/full/path/to/jobFinder/.venv/bin/jobfinder-mcp"
    }
  }
}

El archivo de configuración se encuentra en:

Reinicia Claude Desktop después. Cursor y Windsurf usan el mismo formato command en sus propios ajustes de MCP.

Luego solo pregunta:

"Encuéntrame trabajo remoto de contrato en React en Europa"

Hay cuatro herramientas disponibles: check_setup (confirma que las claves funcionan), preview_search (ve cómo se entendió una solicitud, antes de gastar nada), find_jobs (la ejecución completa — tarda unos minutos y escribe la hoja de cálculo), y list_platforms (qué sitios de empleo sirven a un país).

Claves de API — lo que necesitas y lo que no

Sin ninguna clave, la herramienta aún busca en los listados públicos de LinkedIn, los portales de empleo de empleadores (Greenhouse, Lever, Ashby, Workable y otros), diez portales de trabajo remoto, "Who is hiring" de Hacker News y cualquier portal regional que publique marcado estándar de empleo.

Con la clave de Anthropic (paso 2 anterior), también entiende solicitudes en texto libre, lee tu CV y evalúa elegibilidad y ajuste. Sin ella aún puedes buscar, pero tienes que decir qué buscar en candidate.local.json en lugar de en una frase — ver Solución de problemas.

Todo lo siguiente es opcional. Cada uno añade más sitios de empleo. Omite cualquiera de ellos y la herramienta simplemente informa de que esa fuente no se usa — nunca falla una ejecución.

Claves gratuitas, autoservicio

Regístrate, copia la clave, pégala en .env.

Llegar a Indeed, Glassdoor, Bayt, Naukri y el resto

Esos sitios — además de Rozee y foundit — bloquean las solicitudes directas con un CAPTCHA, pero todos publican en el índice de empleo de Google a propósito. Así que la vía de entrada es el índice de Google, y varios proveedores venden acceso con licencia a él.

Todos devuelven los mismos listados, porque son todos los datos de Google. La elección es el precio y la asignación gratuita, no la cobertura. Elige el que prefieras y pon su clave en .env exactamente como los demás — la herramienta usa el que encuentre:

Usa la variable que coincida con el sitio donde te registraste. Las dos no son intercambiables: una clave de SearchApi.io en SERPAPI_KEY se rechaza con 401 Invalid API key. Las claves de SerpApi son 64 caracteres hexadecimales; las de SearchApi.io son más cortas. Si recibes un rechazo, comprueba qué sitio emitió la clave. Ejecuta jobfinder sources y te dirá qué proveedor está usando.

SERPAPI_KEY=your-key-here

Configura solo una. Si ambas están presentes, se usa el primer proveedor configurado, y ninguna es obligatoria — sin ellas la herramienta aún se ejecuta, simplemente omite esos sitios y lo dice en el resumen de la ejecución.

Si el portal de empleo principal de tu país no está en la lista gratuita anterior, esta es la clave que vale la pena tener: llega a esos sitios en cualquier país. La cobertura varía según el país y según cómo redactes la búsqueda — el índice de Google tiene mucho para "software engineer" en Pakistán y "full stack developer" en los EAU, y nada en absoluto para algunas otras combinaciones. Un resultado vacío se informa como tal, no como una clave rota.

Se necesita aprobación

INDEED_PUBLISHER_ID, ZIPRECRUITER_API_KEY, SEEK_API_KEY, STEPSTONE_API_KEY, BAYT_API_KEY, NAUKRI_API_KEY, ROZEE_API_KEY — estos son programas de socios que deben aprobarte primero. La mayoría de la gente no los necesita; la clave de SerpApi llega a los mismos listados.

Para ver exactamente qué plataformas sirven a tu país y qué claves quieren:

jobfinder setup --region Nigeria

Dónde poner las claves

Cualquiera de estas, la que te convenga:

1. Un archivo que nombres tú mismo, mediante JOBFINDER_ENV=/ruta/a/tu.env

2. .env en la carpeta desde la que ejecutas el comando

3. ~/.jobfinder/.env — una buena opción si quieres un conjunto de claves para cada proyecto

4. .env en la carpeta del proyecto

Todos se leen y se combinan. Para una clave configurada en más de uno, la que esté más arriba en esta lista gana; una clave que solo tenga el archivo inferior aún se recoge. Así que puedes mantener claves compartidas en ~/.jobfinder/.env y las específicas de cada proyecto en el .env del proyecto.

Las variables de entorno reales superan a cualquier archivo, así que export ADZUNA_APP_ID=... gana. Ten en cuenta que lo contrario no se cumple: desactivar una variable en tu shell no oculta una clave que un archivo .env también define. El formato es un CLAVE=valor por línea, sin comillas:

ANTHROPIC_API_KEY=sk-ant-...
ADZUNA_APP_ID=12345678
ADZUNA_APP_KEY=abcdef...

Uso diario

Di lo que quieres, en palabras sencillas. Sin filtros que configurar:

jobfinder daily --query "plumber jobs in Lagos"
jobfinder daily --query "remote React contract, Europe"
jobfinder daily --query "part time warehouse work near Leeds"
jobfinder daily --query "graduate marketing internship, London"

O entrégale tu CV y deja que deduzca a qué te dedicas:

jobfinder daily --cv ~/cv.pdf
jobfinder daily --cv ~/cv.pdf --query "only remote, minimum £45k"

El CV se lee en tu máquina. Solo el texto se envía a Anthropic, para construir tu perfil de búsqueda y puntuar lo bien que encaja cada anuncio.

Banderas útiles:

Cada bandera anterior funciona para cualquier país. --region acepta un país, una ciudad, un nombre nativo o una lista — "uae", "Deutschland", "Lagos", "USA, UK" todos se resuelven.

Sobre --min-salary: un anuncio que no publica salario se mantiene, marcado "Pay not published", porque no se puede demostrar que esté por debajo de tu mínimo. Añade --require-salary si prefieres no verlos en absoluto. Si tu solicitud misma menciona una cifra — --query "electrician jobs, minimum $60k" — los anuncios sin salario publicado se mueven a la hoja de Prospects en su lugar.

Lo que obtienes

Una hoja de cálculo en ~/Desktop/job finder/, con trece hojas: Quick Apply (solo lo esencial), Hot Leads, All Qualified Jobs, luego divisiones por Full Time, Part Time, Contract, Freelance, Startups y Partnerships, además de Prospects (elegibilidad poco clara — vale la pena preguntar), Long Shots (cualificados, pero con baja probabilidad de respuesta), Companies & Contacts y un Search Summary que muestra qué se filtró y por qué.

Los mismos datos se escriben junto a ella como .csv, .json y una página .html navegable.

El % de coincidencia es una estimación de ser preseleccionado, no de solapamiento de palabras clave. El ajuste de tu CV establece el techo; a partir de ahí, la estimación se basa en lo que el anuncio revela sobre la competencia. Cada fila muestra su propia aritmética en la columna "Why this rank":

fit 87 × 1.05 = 91 — applicant count not published (-4%) · posted in the
last 24 hours (+3%) · scoped to United Kingdom, smaller pool (+6%) ·
applying straight into the employer's own system (+5%)

Así que una coincidencia perfecta detrás de 200 solicitantes se clasifica por debajo de una buena coincidencia que nadie ha encontrado todavía — la respuesta honesta sobre dónde va tu tiempo.

Otros comandos

jobfinder setup                 # which keys are set, which are missing
jobfinder setup --region India  # what serves a particular country
jobfinder sources               # every connector and its status
jobfinder sources --test        # live-check every configured key
jobfinder status                # what previous runs found
jobfinder platforms --region Kenya
jobfinder platforms --region Kenya --trade "solar installer"
jobfinder check --title "..." --description "..."   # why one advert passed or failed

check también acepta --company, --location y --url, que le permiten juzgar al empleador, la elegibilidad y cómo te postularías en lugar de solo el texto.

Para hacer que una búsqueda sea tu predeterminada de modo que un simple jobfinder daily la ejecute, crea candidate.local.json en la carpeta del proyecto:

{
  "home_country": "Nigeria",
  "default_search": {
    "label": "Electrical",
    "query": "electrician jobs in Lagos",
    "core_terms": ["electrician", "electrical"]
  }
}

Está en git-ignore. Sin él, un simple jobfinder daily pregunta qué buscar en lugar de adivinar.

Solución de problemas

"No sé qué tipo de trabajo buscar" — dale un --query o un --cv. No inventará una búsqueda por ti.

"Una búsqueda personalizada necesita la capa de juicio de Claude" — un --query en texto libre tiene que ser leído por el modelo antes de poder buscarse, así que esto necesita ANTHROPIC_API_KEY. La ejecución se detiene con el código de salida 1 y no escribe ningún informe. O configura la clave, o indica la búsqueda tú mismo en candidate.local.json como se muestra a continuación.

No se encontraron trabajos — amplía la ventana con --days 30, verifica que tu país esté escrito completo y ejecuta jobfinder setup --region <tu país> para ver si los sitios que te sirven necesitan una clave que no has configurado.

"ANTHROPIC_API_KEY no está configurada" — el archivo .env no está donde la herramienta lo busca, o la clave tiene comillas alrededor. Ejecuta jobfinder setup para ver qué encontró. Recuerda que el archivo debe llamarse .env, no env ni env.txt.

No pasa nada en Windows — instala con pip install -e ".[all]" en lugar de ejecutar directamente desde el código fuente; Windows necesita el paquete tzdata.

¿Quieres ver cómo funciona antes de configurar claves? Una consulta --query de texto libre necesita la clave de Anthropic, porque algo tiene que leer tu frase y convertirla en una búsqueda. Para ejecutarlo sin claves, pasa la búsqueda directamente — pon esto en candidate.local.json en la carpeta del proyecto:

{
  "default_search": {
    "label": "Warehouse",
    "query": "warehouse operative",
    "core_terms": ["warehouse", "forklift"]
  }
}

luego ejecútalo con los anuncios de ejemplo incluidos:

jobfinder daily --offline --no-llm

Eso genera una hoja de cálculo completa sin contactar con nada.

Desarrollo

.venv/bin/pip install -e ".[all,dev]"
.venv/bin/python -m pytest tests/ -q      # 661 tests, fully offline
.venv/bin/ruff check job_agent/ tests/

Las pruebas no necesitan claves ni acceso a la red.

Privacidad

Tu currículum permanece en tu máquina — se lee localmente, y solo el texto extraído se envía a la API de Anthropic, con tu propia clave, para crear tu perfil de búsqueda y evaluar la adecuación. El texto de los anuncios va a la misma API con el mismo propósito, y a ningún otro lugar.

Tus términos de búsqueda se envían a las bolsas de trabajo que hayas habilitado, porque así es como funcionan las búsquedas — las mismas palabras que escribirías en esos sitios. Sin claves configuradas, eso significa la búsqueda pública de LinkedIn y las bolsas de trabajo abiertas. Ejecuta jobfinder sources para ver exactamente cuáles están activas.

Nada se envía al autor de esta herramienta, y no hay telemetría. Las claves de API se leen de .env, que está en git-ignore, y se eliminan de los registros y mensajes de error — una solicitud fallida que incluya una clave en su URL se redacta antes de imprimirse.