freehire MCP servidor

Un servidor MCP sobre la API de empleos de freehire. Permite que cualquier host MCP — Claude Desktop, Claude Code o un agente compatible — busque, filtre y postule a empleos de TI sin navegador, autenticándose con una clave API personal. Las ofertas se extraen directamente de los portales de empleo de las empresas: más de 3,3 millones de puestos abiertos en 294 000 empresas, normalizados en un único esquema y etiquetados con stack, seniority, región y modalidad de trabajo (cifras en vivo).

Refleja el CLI de freehire: misma API, mismas credenciales, expuesto como herramientas MCP en lugar de comandos de shell.

Instalación

No se necesita instalación global: el host lo ejecuta mediante npx. Añádelo a la configuración MCP de tu host (Claude Desktop → Configuración → Desarrollador → Editar configuración, o ~/.claude.json para Claude Code):

{
  "mcpServers": {
    "freehire": {
      "command": "npx",
      "args": ["-y", "freehire-mcp"],
      "env": { "FREEHIRE_TOKEN": "fhk_xxxxxxxx" }
    }
  }
}

Crea la clave fhk_… en la aplicación web (freehire.me → menú de cuenta → Claves API). Si ya usas el CLI de freehire (freehire auth login), puedes omitir env — el servidor lee el mismo ~/.freehire/creds.json.

Related MCP server: job-monitor

Autenticación

El token y la URL base de la API se resuelven con precedencia env → ~/.freehire/creds.json → predeterminado https://freehire.me:

El servidor solo lee el archivo de credenciales (nunca lo escribe; iniciar sesión sigue siendo tarea del CLI). Si no se configura ningún token, las herramientas devuelven un error claro de "no autenticado" en lugar de que el servidor falle al iniciar.

Herramientas

Filtros. search, market_fit y facets comparten los mismos parámetros de filtro de mercado: remote, region, country, city, company, category, role, seniority, employment_type, english_level, exclude_skill, salary_min, visa, más un mapa facets genérico ({"source": "greenhouse"}) para cualquier otra faceta del vocabulario. Descubre los valores válidos con la herramienta facets — no los inventes. En search, skills es un filtro; en market_fit, skills es el conjunto medido.

La geografía amplía. region, country y city son un grupo OR: region: ["eu"] con country: ["IT"] significa "en Europa o en Italia" y devuelve todo lo que la región sola devolvería. Para buscar un solo país, pasa country y omite region. Los tres nombran un único concepto — dónde — por lo que elegir dos lugares se lee como "o", lo que hace útil region: ["eu"] con country: ["BR"] ("Europa o Brasil"). No hay AND que activar: _mode=and no se aplica a la geografía.

Los parámetros no reconocidos se ignoran, no se rechazan. Una clave de filtro que la API no reconoce no hace fallar la solicitud, la amplía. Estas claves aparecen en la lista ignored del resultado, con did_you_mean cuando solo el número gramatical era incorrecto. search lo informa junto a total; facets y market_fit responden un único objeto, por lo que lo envuelven como {data, ignored} — y solo entonces, dejando intacta la forma de una llamada limpia. Cualquier número de un resultado que contenga ignored responde a una pregunta más amplia que la planteada — reintenta con el nombre sugerido antes de informarlo.

Descripciones. search lee el endpoint de agente de la API, por lo que cada resultado ya incluye la descripción completa de la oferta como markdown — un host puede revisar un conjunto de resultados sin una llamada job por cada uno. Las descripciones son largas, así que mantén limit moderado.

La regla de evidencia. Cada logro en el banco registra quién lo afirmó. cv_import, stated_in_chat y manual significan que el candidato lo hizo, y pueden citarse en un CV; agent_inferred significa que un modelo lo leyó en el registro, y no puede. cv_edit rechaza cualquier afirmación sobre el candidato sin un evidence_id que apunte a uno citable, por lo que experience_list es la herramienta que hace que cv_edit sea utilizable.

Corregir un logro no cambia esa etiqueta: uno agent_inferred permanece no citable aunque se reformule. La única forma de que sea citable es preguntar al candidato y luego registrar lo que él diga con experience_add_achievement.

Eliminar es definitivo — el banco no tiene deshacer. Un lugar debe vaciarse antes de poder eliminarse, porque eliminarlo llevaría todos los logros que contiene. Fusionar dos logros en uno, conservando los números de ambos, se hace en el sitio.

Cada herramienta devuelve los data crudos de la API como texto JSON; un error de la API se convierte en un resultado isError que lleva el estado HTTP (un 401 añade una pista de autenticación).

Desarrollo

npm install
npm test        # vitest: config, client (mock server), facets, tool dispatch
npm run build   # tsc → dist/

Licencia

MIT — ver LICENSE. El backend y el CLI de freehire también son MIT.