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

Available Tools

Prerequisites

• Python 3.10+

• 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

Option 1: Install from PyPI (Recommended)

Or use uvx for isolated execution:

Option 2: Install from Source

Option 3: Development Setup

Configure Environment Variables

Create a .env file with your Adzuna credentials:

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

Restart Claude Desktop after updating the configuration.

With Cursor

Add to your Cursor MCP settings (.cursor/mcp.json in your project or global config):

With Other MCP Clients

Run the server directly:

Development Mode

FastMCP provides a dev mode with an interactive inspector:

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:

get_categories

Get valid category tags before searching:

get_salary_histogram

Understand salary distribution:

get_top_companies

Find major employers:

get_geodata

Compare salaries across regions:

get_salary_history

Analyze salary trends:

Important Notes

• Salaries are annual amounts in the local currency of the selected country

• Call 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

Troubleshooting

Server not appearing in Claude Desktop

1. Check the Python path is correct in your config

2. Ensure the virtual environment has all dependencies installed

3. Restart Claude Desktop completely (Cmd+Q / Alt+F4)

4. Check Claude Desktop logs: ~/Library/Logs/Claude/mcp*.log

Authentication errors

1. Verify your API credentials at Adzuna Developer Portal

2. Check the .env file has correct values

3. Ensure environment variables are passed in the MCP config

No results returned

1. Try broader search terms

2. Check the country code is valid

3. Remove salary filters (many jobs don't list salaries)

4. 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.

Acknowledgments

• Adzuna for providing the job search API

• FastMCP for the MCP framework

• Anthropic for the Model Context Protocol specification