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

The server provides several tools that AI assistants can use. Below is the complete list of tools and the parameters they accept:

1. search_jobs

Search for job listings across the supported countries. Parameters:

• country (string, required): ISO 3166-1 alpha-2 country code (e.g., "gb", "us", "in").
• keywords (string, optional): Space-separated search terms (e.g., "frontend nextjs").
• location (string, optional): Geographic filter (city, region, or postal code).
• page (number, optional): Page number for pagination (starts at 1). Default: 1.
• results_per_page (number, optional): Number of results per page (max 50). Default: 10.
• salary_min (number, optional): Minimum annual salary in local currency.
• salary_max (number, optional): Maximum annual salary in local currency.
• full_time (boolean, optional): Set to true to only show full-time jobs.
• part_time (boolean, optional): Set to true to only show part-time jobs.
• contract (boolean, optional): Set to true to only show contract/freelance jobs.
• permanent (boolean, optional): Set to true to only show permanent positions.
• category (string, optional): Specific job category tag (use get_categories to find valid tags).
• sort_by (string, optional): Sort order. Options: "date", "salary", "relevance".
• max_days_old (number, optional): Maximum age of job listings in days.

2. get_categories

Get a list of valid job category tags for a specific country to be used in the category parameter. Parameters:

• country (string, required): ISO 3166-1 alpha-2 country code.

3. get_salary_histogram

Get a salary distribution histogram for jobs matching specific criteria to understand the typical market rates. Parameters:

• country (string, required): ISO 3166-1 alpha-2 country code.
• keywords (string, optional): Search terms to filter jobs.
• location (string, optional): Location filter.
• category (string, optional): Category tag.

4. get_top_companies

Get a list of top employers currently hiring, ranked by the number of open positions. Parameters:

• country (string, required): ISO 3166-1 alpha-2 country code.
• keywords (string, optional): Search terms to filter jobs.
• location (string, optional): Location filter.
• category (string, optional): Category tag.

5. get_geodata

Get salary and job count data broken down by geographic regions to compare different areas. Parameters:

• country (string, required): ISO 3166-1 alpha-2 country code.
• keywords (string, optional): Search terms to filter jobs.
• location (string, optional): Focus region for sub-area breakdown.
• category (string, optional): Category tag.

6. get_salary_history

Analyze how average salaries have trended over time for specific roles. Parameters:

• country (string, required): ISO 3166-1 alpha-2 country code.
• keywords (string, optional): Search terms to filter jobs.
• location (string, optional): Location filter.
• category (string, optional): Category tag.
• months (number, optional): Number of months of history to return (default: 12, max: ~24).

7. get_api_version

Fetch the current Adzuna API version. Parameters: None.

Prerequisites

• Bun installed locally
• Adzuna API credentials (free)

Getting Adzuna API Credentials

1. Go to Adzuna Developer Portal
2. Sign up for a free account
3. Create a new application
4. Copy your App ID and App Key

Installation

git clone https://github.com/jayesh-kr/adzuna-mcp.git
cd adzuna-mcp
bun install

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": "bun",
      "args": ["run", "/path/to/adzuna-mcp/src/index.ts"],
      "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": "bun",
      "args": ["run", "/path/to/adzuna-mcp/src/index.ts"],
      "env": {
        "ADZUNA_APP_ID": "your_app_id",
        "ADZUNA_APP_KEY": "your_app_key"
      }
    }
  }
}

Testing

Run tests locally with Bun:

bun test