# Adzuna Jobs MCP Server

A Model Context Protocol (MCP) server that provides AI assistants with access to the [Adzuna Job Search API](https://developer.adzuna.com/). 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](https://bun.sh/) installed locally
- Adzuna API credentials (free)

## Getting Adzuna API Credentials

1. Go to [Adzuna Developer Portal](https://developer.adzuna.com/)
2. Sign up for a free account
3. Create a new application
4. Copy your **App ID** and **App Key**

## Installation

```bash
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`

```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):

```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"
      }
    }
  }
}
```

## Testing

Run tests locally with Bun:

```bash
bun test
```