Adzuna Jobs MCP Server
A Model Context Protocol (MCP) server that provides AI assistants with access to the Adzuna Job Search API. Search for jobs, analyze salary data, and research employers across 12 countries.
Features
- Job Search - Search millions of job listings with filters for location, salary, job type, and more
- Salary Analysis - Get salary histograms, regional comparisons, and historical trends
- Company Research - Find top employers by hiring volume
- Multi-Country Support - Access job markets in 12 countries with local currency support
Supported Countries
| Code | Country | Currency |
|---|---|---|
gb | United Kingdom | GBP £ |
us | United States | USD $ |
de | Germany | EUR € |
fr | France | EUR € |
au | Australia | AUD $ |
nz | New Zealand | NZD $ |
ca | Canada | CAD $ |
in | India | INR ₹ |
pl | Poland | PLN zł |
br | Brazil | BRL R$ |
at | Austria | EUR € |
za | South Africa | ZAR R |
Available Tools
| Tool | Description |
|---|---|
search_jobs | Search for jobs with filters (keywords, location, salary, job type) |
get_categories | Get valid job category tags for a country |
get_salary_histogram | Get salary distribution data for job searches |
get_top_companies | Get top employers by number of open positions |
get_geodata | Get salary data broken down by geographic region |
get_salary_history | Get historical salary trends over time |
get_api_version | Get current Adzuna API version |
Prerequisites
- Python 3.10+
- Adzuna API credentials (free)
Getting Adzuna API Credentials
- Go to Adzuna Developer Portal
- Sign up for a free account
- Create a new application
- Copy your App ID and App Key
Installation
Option 1: Install from PyPI (Recommended)
pip install adzuna-mcp
Or use uvx for isolated execution:
uvx adzuna-mcp
Option 2: Install from Source
git clone https://github.com/folarinakinloye/adzuna-mcp.git
cd adzuna-mcp
pip install -e .
Option 3: Development Setup
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]"
Configure Environment Variables
Create a .env file with your Adzuna credentials:
ADZUNA_APP_ID=your_app_id_here
ADZUNA_APP_KEY=your_app_key_here
Usage
With Claude Desktop
Add to your Claude Desktop configuration file:
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"
}
}
}
}
Restart Claude Desktop after updating the configuration.
With Cursor
Add to your Cursor MCP settings (.cursor/mcp.json in your project or global config):
{
"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"
}
}
}
}
With Other MCP Clients
Run the server directly:
# Activate virtual environment
source venv/bin/activate
# Run with stdio transport (default)
python server.py
# Or use FastMCP CLI
fastmcp run server.py:mcp
Development Mode
FastMCP provides a dev mode with an interactive inspector:
fastmcp dev server.py
This opens a browser-based UI to test your tools.
Example Prompts
Once connected, you can ask your AI assistant:
Job Search:
- "Find software engineer jobs in London paying over £60,000"
- "Search for remote Python developer positions in the US"
- "Show me data science jobs in Germany"
Salary Research:
- "What's the typical salary for a machine learning engineer in the UK?"
- "Compare software engineer salaries between London and Manchester"
- "How have data scientist salaries changed over the past year?"
Company Research:
- "Which companies are hiring the most software engineers in London?"
- "Show me the top employers for finance jobs in New York"
Tool Details
search_jobs
Search for jobs with comprehensive filtering:
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
Get valid category tags before searching:
Parameters:
- country (required): Country code
Returns category tags like "it-jobs", "engineering-jobs", "finance-jobs"
get_salary_histogram
Understand salary distribution:
Parameters:
- country (required): Country code
- keywords: Filter by job type
- location: Filter by location
- category: Filter by category
get_top_companies
Find major employers:
Parameters:
- country (required): Country code
- keywords: Filter by job type
- location: Filter by location
- category: Filter by category
get_geodata
Compare salaries across regions:
Parameters:
- country (required): Country code
- keywords: Filter by job type
- location: Focus on sub-regions
- category: Filter by category
get_salary_history
Analyze salary trends:
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)
Important Notes
- Salaries are annual amounts in the local currency of the selected country
- Call
get_categoriesfirst to get valid category tags for your country - Many jobs don't list salaries - salary filters will exclude these jobs
- Rate limits apply - the Adzuna API has usage limits on free tier
Project Structure
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
Troubleshooting
Server not appearing in Claude Desktop
- Check the Python path is correct in your config
- Ensure the virtual environment has all dependencies installed
- Restart Claude Desktop completely (Cmd+Q / Alt+F4)
- Check Claude Desktop logs:
~/Library/Logs/Claude/mcp*.log
Authentication errors
- Verify your API credentials at Adzuna Developer Portal
- Check the
.envfile has correct values - Ensure environment variables are passed in the MCP config
No results returned
- Try broader search terms
- Check the country code is valid
- Remove salary filters (many jobs don't list salaries)
- Verify the category tag is valid for that country
Contributing
Contributions are welcome! Please see CONTRIBUTING.md for guidelines.
License
MIT License - see LICENSE for details.
