get_api_version
Get the current Adzuna API version.
Returns: API version information
LABSCO SUMMARY
The salary tools are the reason to attach it, not the listings.
Job listings you can find anywhere; a salary histogram, a regional breakdown and a year of history for the same query are what let you answer whether an offer is good rather than whether it exists. Two things will quietly narrow your results: call get_categories first, because valid category tags differ by country, and remember that a salary filter drops every listing that does not publish a salary — which is a lot of them.
What it is
An MCP server over the Adzuna Job Search API, covering both sides of a job search: the listings themselves, and the market data around them. Each country is queried by its code, and salaries come back as annual amounts in that country's currency.
What you get
- Job listings searched by keywords, location, salary floor and ceiling, category, and job type — full time, part time, contract or permanent — sorted by date, salary or relevance, with a maximum listing age and up to 50 results per page —
search_jobs - The valid category tags for a country, such as
it-jobsorfinance-jobs, which is what makes category filtering work —get_categories - Salary distribution for a search, so a number can be read against the spread rather than against an average —
get_salary_histogram - Salaries broken down by geographic region, for comparing one city against another —
get_geodata - Historical salary movement over a period you choose, defaulting to 12 months —
get_salary_history - The employers with the most open positions for a search —
get_top_companies - The Adzuna API version currently in use —
get_api_version - Twelve country markets:
gb,us,de,fr,au,nz,ca,in,pl,br,atandza, each with its local currency
Requirements
An Adzuna developer account, which is free: it gives you an App ID and an App Key, supplied as ADZUNA_APP_ID and ADZUNA_APP_KEY. Python 3.10+. The README names the package adzuna-mcp, which PyPI does not have. The free tier carries Adzuna's usage limits, so batch broad research rather than polling.
Setup effort
Build from source — git clone https://github.com/folathecoder/adzuna-job-search-mcp.git
USE CASES
01
Finding out whether an offer is fair
Pull the salary histogram for that role and location to see the whole distribution, then check how it has moved over the past year.
02
Deciding where to look for work
Compare salaries by region for the same role, so a higher number in one city is read against what the job market there actually pays.
03
Running a targeted job search
Get the country's category tags, then search that category with your location, salary floor and job type, sorted by date.
04
Working out who is actually hiring
List the top employers by open positions for a role and location, and use that as the shortlist rather than applying to postings one at a time.
05
Researching a market before relocating
Run the same role across two country codes and compare volume, salary distribution and top employers side by side.
7 tools
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
get_categories
Get valid job category tags for a specific country.
PURPOSE: Use this BEFORE search_jobs to get valid 'category' parameter values. Category tags are COUNTRY-SPECIFIC - always use the same country code here as you will in search_jobs.
Args: country: ISO 3166-1 alpha-2 country code. Supported: "gb", "us", "de", "fr", "au", "nz", "ca", "in", "pl", "br", "at", "za"
Returns: dict: Contains "results" array of category objects:
- tag: Use THIS value in search_jobs category parameter (e.g., "it-jobs")
- label: Human-readable name for display (e.g., "IT Jobs")
Common category tags (vary by country):
- "it-jobs": Technology, software, IT support
- "engineering-jobs": Mechanical, electrical, civil
- "finance-jobs": Accounting, banking, financial services
- "sales-jobs": Sales, business development
- "healthcare-nursing-jobs": Medical, nursing
- "admin-jobs": Administration, office support
- "marketing-jobs": Marketing, PR, communications
Example response: { "results": [ {"tag": "it-jobs", "label": "IT Jobs"}, {"tag": "engineering-jobs", "label": "Engineering Jobs"}, {"tag": "finance-jobs", "label": "Accounting & Finance Jobs"} ] }
Usage: categories = get_categories("gb") search_jobs(country="gb", category="it-jobs") # Use tag, not label
Errors:
- Invalid country code: "API Error 400: Invalid country"
- Rate limit exceeded: "API Error 429: Too many requests"
- Authentication failure: "API Error 401: Invalid credentials"
get_geodata
Get salary and job count data broken down by geographic region.
PURPOSE: Compare salaries and job availability across areas. Useful for:
- "Where are the highest paying X jobs?"
- "Which cities have the most opportunities?"
- Relocation decisions
Args: country: ISO 3166-1 alpha-2 country code. Supported: "gb", "us", "de", "fr", "au", "nz", "ca", "in", "pl", "br", "at", "za"
keywords: Filter to specific roles (e.g., "software engineer").
location: Focus on a region for sub-area breakdown.
- Empty: National breakdown (London, Manchester, etc.)
- "London": Breakdown within London (City, Canary Wharf, etc.)
category: Category tag from get_categories (e.g., "it-jobs").
Returns: dict: Contains "locations" array of region objects:
- location.display_name: Region name
- location.area: Geographic hierarchy array
- count: Number of jobs in region
- average_salary: Average salary (may be null)
Example response: { "locations": [ { "location": {"display_name": "London", "area": ["UK", "London"]}, "count": 15678, "average_salary": 62000 }, { "location": {"display_name": "Manchester", "area": ["UK", "Manchester"]}, "count": 3456, "average_salary": 48000 } ] }
Notes:
- Results ordered by job count (most jobs first)
- average_salary is ANNUAL in LOCAL CURRENCY
- Typically returns 10-20 top regions
Errors:
- Invalid country code: "API Error 400: Invalid country"
- Invalid category: "API Error 400: Invalid category tag"
- Rate limit exceeded: "API Error 429: Too many requests"
- Authentication failure: "API Error 401: Invalid credentials"
get_salary_histogram
Get salary distribution histogram for jobs matching search criteria.
PURPOSE: Understand salary ranges in a job market. Useful for:
- "What's the typical salary for X role?"
- Salary negotiation research
- Market positioning analysis
IMPORTANT: Only includes jobs WITH listed salaries. Many jobs don't list salary.
Args: country: ISO 3166-1 alpha-2 country code. Determines currency. Supported: "gb", "us", "de", "fr", "au", "nz", "ca", "in", "pl", "br", "at", "za"
keywords: Search terms to filter jobs (e.g., "software engineer", "data scientist").
location: Location filter (e.g., "London", "New York").
category: Category tag from get_categories (e.g., "it-jobs").
Returns: dict: Contains "histogram" object with salary buckets:
- Keys: Salary values as strings (e.g., "30000", "35000")
- Values: Number of jobs at that salary point
Example response: { "histogram": { "25000": 89, "30000": 234, "35000": 456, "40000": 567, "45000": 489, "50000": 378, "55000": 245, "60000": 167 } }
How to interpret:
- Keys are ANNUAL salaries in LOCAL CURRENCY
- Buckets are typically £5,000 / $5,000 increments
- Peak of distribution = most common salary
- To find median: find salary where cumulative count reaches 50%
Errors:
- Invalid country code: "API Error 400: Invalid country"
- Invalid category: "API Error 400: Invalid category tag"
- Rate limit exceeded: "API Error 429: Too many requests"
- Authentication failure: "API Error 401: Invalid credentials"
get_salary_history
Get historical salary trends over time for matching jobs.
PURPOSE: Analyze how salaries have changed. Useful for:
- "Are X salaries going up or down?"
- Trend analysis for negotiations
- Market timing for job searches
Args: country: ISO 3166-1 alpha-2 country code. Supported: "gb", "us", "de", "fr", "au", "nz", "ca", "in", "pl", "br", "at", "za"
keywords: Filter to specific roles (e.g., "software engineer").
location: Location filter (e.g., "London").
category: Category tag from get_categories (e.g., "it-jobs").
months: Number of months of history (default 12, max ~24).
- 6: Recent trend
- 12: Year-over-year comparison
- 24: Longer-term view
Returns: dict: Contains "month" array of data points:
- month: Year-month string (YYYY-MM format)
- salary: Average salary that month (annual, local currency)
Example response: { "month": [ {"month": "2024-01", "salary": 52000}, {"month": "2024-02", "salary": 52500}, {"month": "2024-03", "salary": 53000} ] }
How to analyze:
- Compare first vs last month for overall change
- Calculate % change: ((last - first) / first) * 100
- Look for consistent direction vs volatility
Errors:
- Invalid country code: "API Error 400: Invalid country"
- Invalid category: "API Error 400: Invalid category tag"
- Rate limit exceeded: "API Error 429: Too many requests"
- Authentication failure: "API Error 401: Invalid credentials"
get_top_companies
Get top employers currently hiring, ranked by number of open positions.
PURPOSE: Identify major employers in a field. Useful for:
- "Which companies are hiring the most engineers?"
- Researching potential employers
- Understanding market leaders by hiring volume
NOTE: Shows hiring VOLUME, not company quality. Smaller great companies may not appear.
Args: country: ISO 3166-1 alpha-2 country code. Supported: "gb", "us", "de", "fr", "au", "nz", "ca", "in", "pl", "br", "at", "za"
keywords: Filter to specific roles (e.g., "software engineer", "data scientist").
location: Location filter (e.g., "London" for London-based employers).
category: Category tag from get_categories (e.g., "it-jobs").
Returns: dict: Contains "leaderboard" array of company objects:
- canonical_name: Company name (normalized)
- count: Number of open positions
- average_salary: Average salary across listings (may be null)
Example response: { "leaderboard": [ {"canonical_name": "NHS", "count": 1245, "average_salary": 42000}, {"canonical_name": "Amazon", "count": 567, "average_salary": 65000}, {"canonical_name": "Google", "count": 234, "average_salary": 95000} ] }
Notes:
- Ranked by job count (most positions first)
- Typically returns 10-20 companies
- average_salary is ANNUAL in LOCAL CURRENCY (may be null)
Errors:
- Invalid country code: "API Error 400: Invalid country"
- Invalid category: "API Error 400: Invalid category tag"
- Rate limit exceeded: "API Error 429: Too many requests"
- Authentication failure: "API Error 401: Invalid credentials"
search_jobs
Search for jobs on Adzuna across 12 supported countries.
IMPORTANT: All salary figures are ANNUAL amounts in LOCAL CURRENCY.
Args: country: ISO 3166-1 alpha-2 country code. Determines job market AND currency. Supported: "gb" (UK/GBP), "us" (USA/USD), "de" (Germany/EUR), "fr" (France/EUR), "au" (Australia/AUD), "nz" (New Zealand/NZD), "ca" (Canada/CAD), "in" (India/INR), "pl" (Poland/PLN), "br" (Brazil/BRL), "at" (Austria/EUR), "za" (South Africa/ZAR)
keywords: Space-separated search terms matched against job title and description.
- Terms are OR'd together (more matches = higher ranking)
- Case insensitive
- No boolean operators (AND/OR/NOT not supported) Examples: "python developer", "machine learning engineer", "senior react"
location: Geographic filter with fuzzy matching. Accepts: city names, regions, postal code prefixes. Examples: "London", "Manchester", "SW1" (UK), "New York", "10001" (US) Leave empty for country-wide search. For remote jobs, include "remote" in keywords.
page: Page number for pagination (starts at 1, not 0).
results_per_page: Results per page (default 10, max 50).
salary_min: Minimum ANNUAL salary filter in LOCAL CURRENCY (e.g., 50000 not 50). Note: Jobs without listed salaries are excluded when using this filter.
salary_max: Maximum ANNUAL salary filter in LOCAL CURRENCY.
full_time: Set True to show ONLY full-time jobs.
part_time: Set True to show ONLY part-time jobs.
contract: Set True to show ONLY contract/freelance jobs.
permanent: Set True to show ONLY permanent positions.
category: Job category tag from get_categories tool. Common tags: "it-jobs", "engineering-jobs", "finance-jobs", "sales-jobs" IMPORTANT: Call get_categories(country) first to get valid tags.
sort_by: Sort order - "date" (newest first), "salary" (highest first), "relevance" (best match, default).
max_days_old: Maximum age of listings in days (e.g., 7 for last week).
Returns: dict: Search results containing:
- count (int): Total matching jobs (for pagination)
- results (list): Job listings, each with:
- id: Unique job identifier
- title: Job title
- company.display_name: Employer name
- location.display_name: Job location
- description: Truncated job description (~150 chars)
- redirect_url: URL to apply (via Adzuna redirect)
- created: ISO 8601 posting date
- salary_min, salary_max: Annual salary range (may be null)
- salary_is_predicted: "1" if Adzuna estimated the salary from job description, "0" if the employer explicitly listed the salary. Predicted salaries are less reliable for negotiation.
- contract_type: "permanent", "contract", etc.
- contract_time: "full_time", "part_time"
- category.tag: Category identifier
Example response: { "count": 523, "results": [{ "id": "4123456789", "title": "Senior Software Engineer", "company": {"display_name": "Tech Corp"}, "location": {"display_name": "London"}, "salary_min": 70000, "salary_max": 90000, "redirect_url": "https://www.adzuna.co.uk/..." }] }
Errors:
- Invalid country code: "API Error 400: Invalid country"
- Invalid category: "API Error 400: Invalid category tag"
- Rate limit exceeded: "API Error 429: Too many requests"
- Authentication failure: "API Error 401: Invalid credentials"
BEFORE YOU INSTALL
What to know first
Tools you get
7 tools when we connected.
Requires
- Python 3.10+
- ADZUNA_APP_ID in your environment
- ADZUNA_APP_KEY in your environment
Where it runs
Both documented clients run the server on your machine.
CONTEXT COST
Moderate Standing cost
Rated by the size of the 7 tool definitions that ride along on every turn, not by how many there are
INSTALLATION
Connect your client
Server setup
TERMINAL
git clone https://github.com/folathecoder/adzuna-job-search-mcp.git
cd adzuna-job-search-mcp
python3 -m venv venv
source venv/bin/activate
pip install -e .MCP Clients
Claude Desktop, Cursor
JSON
{
"mcpServers": {
"adzuna-jobs": {
"command": "<YOUR_PATH_TO_ADZUNA_JOB_SEARCH_MCP>/venv/bin/python",
"args": [
"<YOUR_PATH_TO_ADZUNA_JOB_SEARCH_MCP>/server.py"
],
"env": {
"ADZUNA_APP_ID": "<YOUR_ADZUNA_APP_ID>",
"ADZUNA_APP_KEY": "<YOUR_ADZUNA_APP_KEY>"
}
}
}
}
