Adzuna Job Search MCP

Servidor MCP de Empleos de Adzuna

Un servidor de Protocolo de Contexto de Modelo (MCP) que proporciona a los asistentes de IA acceso a la API de Búsqueda de Empleos de Adzuna. Busca empleos, analiza datos salariales e investiga empleadores en 12 países.

Características

• Búsqueda de Empleos - Busca millones de ofertas de empleo con filtros de ubicación, salario, tipo de empleo y más
• Análisis Salarial - Obtén histogramas salariales, comparaciones regionales y tendencias históricas
• Investigación de Empresas - Encuentra los principales empleadores por volumen de contratación
• Soporte Multi-País - Accede a mercados laborales en 12 países con soporte de moneda local

Países Soportados

Código	País	Moneda
gb	Reino Unido	GBP £
us	Estados Unidos	USD $
de	Alemania	EUR €
fr	Francia	EUR €
au	Australia	AUD $
nz	Nueva Zelanda	NZD $
ca	Canadá	CAD $
in	India	INR ₹
pl	Polonia	PLN zł
br	Brasil	BRL R$
at	Austria	EUR €
za	Sudáfrica	ZAR R

Herramientas Disponibles

Herramienta	Descripción
search_jobs	Busca empleos con filtros (palabras clave, ubicación, salario, tipo de empleo)
get_categories	Obtén etiquetas de categorías de empleo válidas para un país
get_salary_histogram	Obtén datos de distribución salarial para búsquedas de empleo
get_top_companies	Obtén los principales empleadores por número de puestos abiertos
get_geodata	Obtén datos salariales desglosados por región geográfica
get_salary_history	Obtén tendencias salariales históricas a lo largo del tiempo
get_api_version	Obtén la versión actual de la API de Adzuna

Requisitos Previos

• Python 3.10+
• Credenciales de la API de Adzuna (gratuitas)

Cómo Obtener Credenciales de la API de Adzuna

1. Ve al Portal de Desarrolladores de Adzuna
2. Regístrate para obtener una cuenta gratuita
3. Crea una nueva aplicación
4. Copia tu ID de Aplicación y Clave de Aplicación

Instalación

Opción 1: Instalar desde PyPI (Recomendado)

pip install adzuna-mcp

O usa uvx para ejecución aislada:

uvx adzuna-mcp

Opción 2: Instalar desde el Código Fuente

git clone https://github.com/folarinakinloye/adzuna-mcp.git
cd adzuna-mcp
pip install -e .

Opción 3: Configuración de Desarrollo

git clone https://github.com/folarinakinloye/adzuna-mcp.git
cd adzuna-mcp
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e ".[dev]"

Configurar Variables de Entorno

Crea un archivo .env con tus credenciales de Adzuna:

ADZUNA_APP_ID=your_app_id_here
ADZUNA_APP_KEY=your_app_key_here

Uso

Con Claude Desktop

Añade a tu archivo de configuración de Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "adzuna-jobs": {
      "command": "/path/to/adzuna-mcp/venv/bin/python",
      "args": ["/path/to/adzuna-mcp/server.py"],
      "env": {
        "ADZUNA_APP_ID": "your_app_id",
        "ADZUNA_APP_KEY": "your_app_key"
      }
    }
  }
}

Reinicia Claude Desktop después de actualizar la configuración.

Con Cursor

Añade a la configuración de MCP de Cursor (.cursor/mcp.json en tu proyecto o configuración global):

{
  "mcpServers": {
    "adzuna-jobs": {
      "command": "/path/to/adzuna-mcp/venv/bin/python",
      "args": ["/path/to/adzuna-mcp/server.py"],
      "env": {
        "ADZUNA_APP_ID": "your_app_id",
        "ADZUNA_APP_KEY": "your_app_key"
      }
    }
  }
}

Con Otros Clientes MCP

Ejecuta el servidor directamente:

# Activate virtual environment
source venv/bin/activate

# Run with stdio transport (default)
python server.py

# Or use FastMCP CLI
fastmcp run server.py:mcp

Modo de Desarrollo

FastMCP proporciona un modo de desarrollo con un inspector interactivo:

fastmcp dev server.py

Esto abre una interfaz de usuario basada en navegador para probar tus herramientas.

Ejemplos de Prompts

Una vez conectado, puedes preguntar a tu asistente de IA:

Búsqueda de Empleos:

• "Encuentra empleos de ingeniero de software en Londres que paguen más de £60,000"
• "Busca puestos de desarrollador Python remoto en EE. UU."
• "Muéstrame empleos de ciencia de datos en Alemania"

Investigación Salarial:

• "¿Cuál es el salario típico de un ingeniero de aprendizaje automático en el Reino Unido?"
• "Compara los salarios de ingenieros de software entre Londres y Mánchester"
• "¿Cómo han cambiado los salarios de los científicos de datos en el último año?"

Investigación de Empresas:

• "¿Qué empresas están contratando más ingenieros de software en Londres?"
• "Muéstrame los principales empleadores para empleos de finanzas en Nueva York"

Detalles de las Herramientas

search_jobs

Busca empleos con filtrado completo:

Parameters:
- country (required): Country code (e.g., "gb", "us")
- keywords: Search terms (e.g., "python developer")
- location: City, region, or postal code
- page: Page number (starts at 1)
- results_per_page: Results per page (max 50)
- salary_min/salary_max: Annual salary filter
- full_time/part_time/contract/permanent: Job type filters
- category: Category tag from get_categories
- sort_by: "date", "salary", or "relevance"
- max_days_old: Maximum listing age in days

get_categories

Obtén etiquetas de categorías válidas antes de buscar:

Parameters:
- country (required): Country code

Returns category tags like "it-jobs", "engineering-jobs", "finance-jobs"

get_salary_histogram

Comprende la distribución salarial:

Parameters:
- country (required): Country code
- keywords: Filter by job type
- location: Filter by location
- category: Filter by category

get_top_companies

Encuentra los principales empleadores:

Parameters:
- country (required): Country code
- keywords: Filter by job type
- location: Filter by location
- category: Filter by category

get_geodata

Compara salarios entre regiones:

Parameters:
- country (required): Country code
- keywords: Filter by job type
- location: Focus on sub-regions
- category: Filter by category

get_salary_history

Analiza tendencias salariales:

Parameters:
- country (required): Country code
- keywords: Filter by job type
- location: Filter by location
- category: Filter by category
- months: Months of history (default 12, max ~24)

Notas Importantes

• Los salarios son montos anuales en la moneda local del país seleccionado
• Llama a get_categories primero para obtener etiquetas de categorías válidas para tu país
• Muchos empleos no listan salarios - los filtros de salario excluirán estos empleos
• Se aplican límites de tasa - la API de Adzuna tiene límites de uso en el plan gratuito

Estructura del Proyecto

adzuna-mcp/
├── server.py              # Main MCP server
├── pyproject.toml         # Package configuration
├── requirements.txt       # Python dependencies
├── .env.example           # Environment template
├── .env                   # Your credentials (gitignored)
├── tests/                 # Test suite
│   ├── __init__.py
│   └── test_server.py
├── .github/
│   └── workflows/
│       ├── ci.yml         # CI pipeline
│       └── publish.yml    # PyPI publishing
├── CONTRIBUTING.md        # Contribution guide
├── LICENSE
├── .gitignore
└── README.md

Solución de Problemas

El servidor no aparece en Claude Desktop

1. Verifica que la ruta de Python sea correcta en tu configuración
2. Asegúrate de que el entorno virtual tenga todas las dependencias instaladas
3. Reinicia Claude Desktop por completo (Cmd+Q / Alt+F4)
4. Revisa los registros de Claude Desktop: ~/Library/Logs/Claude/mcp*.log

Errores de autenticación

1. Verifica tus credenciales de API en el Portal de Desarrolladores de Adzuna
2. Revisa que el archivo .env tenga los valores correctos
3. Asegúrate de que las variables de entorno se pasen en la configuración de MCP

No se devuelven resultados

1. Prueba con términos de búsqueda más amplios
2. Verifica que el código de país sea válido
3. Elimina los filtros de salario (muchos empleos no listan salarios)
4. Verifica que la etiqueta de categoría sea válida para ese país

Contribuciones

¡Las contribuciones son bienvenidas! Consulta CONTRIBUTING.md para las pautas.

Licencia

Licencia MIT - consulta LICENSE para más detalles.

Agradecimientos

• Adzuna por proporcionar la API de búsqueda de empleos
• FastMCP por el marco de trabajo de MCP
• Anthropic por la especificación del Protocolo de Contexto de Modelo