Adzuna Job Search MCP

Servidor MCP de Empregos Adzuna

Um servidor Model Context Protocol (MCP) que fornece a assistentes de IA acesso à API de Busca de Empregos Adzuna. Pesquise empregos, analise dados salariais e pesquise empregadores em 12 países.

Recursos

• Busca de Empregos - Pesquise milhões de anúncios de emprego com filtros por localização, salário, tipo de vaga e mais
• Análise Salarial - Obtenha histogramas salariais, comparações regionais e tendências históricas
• Pesquisa de Empresas - Encontre os principais empregadores por volume de contratações
• Suporte Multi-País - Acesse mercados de trabalho em 12 países com suporte a moedas locais

Países Suportados

Código	País	Moeda
gb	Reino Unido	GBP £
us	Estados Unidos	USD $
de	Alemanha	EUR €
fr	França	EUR €
au	Austrália	AUD $
nz	Nova Zelândia	NZD $
ca	Canadá	CAD $
in	Índia	INR ₹
pl	Polônia	PLN zł
br	Brasil	BRL R$
at	Áustria	EUR €
za	África do Sul	ZAR R

Ferramentas Disponíveis

Ferramenta	Descrição
search_jobs	Pesquise empregos com filtros (palavras-chave, localização, salário, tipo de vaga)
get_categories	Obtenha tags válidas de categorias de empregos para um país
get_salary_histogram	Obtenha dados de distribuição salarial para buscas de empregos
get_top_companies	Obtenha os principais empregadores por número de vagas abertas
get_geodata	Obtenha dados salariais divididos por região geográfica
get_salary_history	Obtenha tendências salariais históricas ao longo do tempo
get_api_version	Obtenha a versão atual da API Adzuna

Pré-requisitos

• Python 3.10+
• Credenciais da API Adzuna (gratuitas)

Obtendo Credenciais da API Adzuna

1. Acesse o Portal do Desenvolvedor Adzuna
2. Cadastre-se para uma conta gratuita
3. Crie um novo aplicativo
4. Copie seu App ID e App Key

Instalação

Opção 1: Instalar via PyPI (Recomendado)

pip install adzuna-mcp

Ou use uvx para execução isolada:

uvx adzuna-mcp

Opção 2: Instalar a partir do Código Fonte

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

Opção 3: Configuração de Desenvolvimento

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 Variáveis de Ambiente

Crie um arquivo .env com suas credenciais Adzuna:

ADZUNA_APP_ID=your_app_id_here
ADZUNA_APP_KEY=your_app_key_here

Uso

Com o Claude Desktop

Adicione ao arquivo de configuração do 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"
      }
    }
  }
}

Reinicie o Claude Desktop após atualizar a configuração.

Com o Cursor

Adicione às configurações MCP do Cursor (.cursor/mcp.json no seu projeto ou configuração 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"
      }
    }
  }
}

Com Outros Clientes MCP

Execute o servidor diretamente:

# 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 Desenvolvimento

O FastMCP fornece um modo de desenvolvimento com um inspetor interativo:

fastmcp dev server.py

Isso abre uma interface baseada em navegador para testar suas ferramentas.

Exemplos de Prompts

Uma vez conectado, você pode perguntar ao seu assistente de IA:

Busca de Empregos:

• "Encontre empregos de engenheiro de software em Londres pagando mais de £60.000"
• "Pesquise vagas remotas de desenvolvedor Python nos EUA"
• "Mostre-me empregos de ciência de dados na Alemanha"

Pesquisa Salarial:

• "Qual é o salário típico para um engenheiro de machine learning no Reino Unido?"
• "Compare salários de engenheiros de software entre Londres e Manchester"
• "Como os salários de cientistas de dados mudaram no último ano?"

Pesquisa de Empresas:

• "Quais empresas estão contratando mais engenheiros de software em Londres?"
• "Mostre-me os principais empregadores para empregos de finanças em Nova York"

Detalhes das Ferramentas

search_jobs

Pesquise empregos com filtragem abrangente:

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

Obtenha tags válidas de categorias antes de pesquisar:

Parameters:
- country (required): Country code

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

get_salary_histogram

Entenda a distribuição salarial:

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

get_top_companies

Encontre os principais empregadores:

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

get_geodata

Compare salários entre regiões:

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

get_salary_history

Analise tendências salariais:

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

• Salários são valores anuais na moeda local do país selecionado
• Chame get_categories primeiro para obter tags válidas de categorias para o seu país
• Muitos empregos não listam salários - filtros salariais excluirão esses empregos
• Limites de taxa se aplicam - a API Adzuna tem limites de uso no plano gratuito

Estrutura do Projeto

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

Solução de Problemas

Servidor não aparecendo no Claude Desktop

1. Verifique se o caminho do Python está correto na sua configuração
2. Garanta que o ambiente virtual tenha todas as dependências instaladas
3. Reinicie o Claude Desktop completamente (Cmd+Q / Alt+F4)
4. Verifique os logs do Claude Desktop: ~/Library/Logs/Claude/mcp*.log

Erros de autenticação

1. Verifique suas credenciais da API no Portal do Desenvolvedor Adzuna
2. Verifique se o arquivo .env tem os valores corretos
3. Garanta que as variáveis de ambiente sejam passadas na configuração MCP

Nenhum resultado retornado

1. Tente termos de busca mais amplos
2. Verifique se o código do país é válido
3. Remova filtros salariais (muitos empregos não listam salários)
4. Verifique se a tag de categoria é válida para aquele país

Contribuindo

Contribuições são bem-vindas! Consulte CONTRIBUTING.md para diretrizes.

Licença

Licença MIT - consulte LICENSE para detalhes.

Agradecimentos

• Adzuna por fornecer a API de busca de empregos
• FastMCP pelo framework MCP
• Anthropic pela especificação do Model Context Protocol