adzuna-job-search-mcp
MCP ServerFreeA 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
Capabilities12 decomposed
multi-country job search with contextual filtering
Medium confidenceExecutes structured queries against the Adzuna Job Search API across 12 countries, supporting keyword matching, location-based filtering, salary range constraints, job type classification (full-time/part-time/contract/permanent), category tags, and relevance/date/salary sorting. The MCP server translates natural language search intents into parameterized API calls with country-specific currency handling and pagination support (up to 50 results per page), enabling AI assistants to discover job listings without direct API credential exposure.
Implements MCP protocol binding to Adzuna API with transparent country-currency mapping and category validation, allowing AI assistants to search job markets across 12 countries without managing API credentials or understanding regional data structures. Uses FastMCP framework for stdio-based transport and automatic tool schema generation from Python function signatures.
Provides unified multi-country job search through a single MCP interface with local currency support, whereas direct Adzuna API usage requires developers to manage country-specific endpoints and currency conversions manually.
salary distribution analysis with histogram generation
Medium confidenceRetrieves salary histogram data from Adzuna API showing the distribution of compensation across job listings, bucketed by salary ranges. Supports filtering by keywords, location, and category to narrow the salary distribution context. Returns structured histogram data (salary ranges and frequency counts) enabling AI assistants to understand typical compensation bands, identify outliers, and advise users on market-competitive salary expectations without requiring statistical computation.
Wraps Adzuna's salary histogram endpoint in MCP protocol, exposing pre-computed salary distributions without requiring the AI assistant to aggregate or bucket raw job data. Supports contextual filtering (keywords, location, category) to generate histograms for specific job market segments.
Eliminates need for AI assistants to fetch all job listings and compute histograms themselves; Adzuna API pre-aggregates this data server-side, reducing latency and API call volume compared to client-side aggregation approaches.
environment variable-based credential management
Medium confidenceManages Adzuna API credentials (App ID and App Key) via environment variables (ADZUNA_APP_ID and ADZUNA_APP_KEY) rather than hardcoding or prompting at runtime. The MCP server reads credentials from the environment at startup and uses them for all subsequent API requests. This pattern is compatible with MCP client configuration files (Claude Desktop, Cursor) that allow environment variables to be specified per MCP server instance, enabling secure credential isolation without exposing secrets in code or configuration files.
Integrates with MCP client configuration files (Claude Desktop, Cursor) to allow per-server environment variable specification, enabling secure credential isolation without requiring users to manage .env files manually. The server reads credentials at startup and validates them implicitly through the first API call.
More secure than hardcoding credentials because secrets are not stored in code; more flexible than prompt-based credential entry because credentials can be configured per MCP server instance in client configuration files.
fastmcp development mode with interactive tool testing
Medium confidenceProvides a development mode (fastmcp dev) that launches an interactive browser-based UI for testing MCP tools without requiring a full MCP client setup. The development mode allows developers to invoke tools, inspect parameters, and view results in real-time, accelerating the development and debugging cycle. This is useful for testing tool schemas, validating API responses, and experimenting with filter combinations before deploying to production MCP clients.
FastMCP's dev mode provides a zero-setup interactive testing environment for MCP tools, eliminating the need to configure Claude Desktop or Cursor during development. The browser-based UI allows developers to test tools and inspect results without writing test code.
Faster development iteration than testing through Claude Desktop because there's no client restart required; more accessible than command-line testing because the UI is visual and interactive.
geographic salary comparison across regions
Medium confidenceQueries Adzuna's geodata endpoint to retrieve salary statistics broken down by geographic regions (cities, states, or postal areas) within a country. Enables comparative analysis of compensation across locations by filtering on keywords, location focus, and category. Returns structured geographic data with salary metrics per region, allowing AI assistants to help users understand regional salary variations and cost-of-living adjusted compensation differences.
Exposes Adzuna's geodata API through MCP, enabling AI assistants to perform multi-region salary comparisons without fetching and aggregating individual job listings. Supports contextual filtering to isolate salary data for specific job types or locations.
Provides pre-aggregated regional salary data via API rather than requiring manual aggregation of job listings; faster and more efficient than client-side geographic bucketing of raw job data.
historical salary trend analysis with time-series data
Medium confidenceRetrieves historical salary trend data from Adzuna API showing how compensation has evolved over time (up to ~24 months of history). Supports filtering by keywords, location, and category to track salary trends for specific job markets. Returns time-series data with salary metrics per month, enabling AI assistants to identify salary growth patterns, seasonal variations, and long-term market compensation trends.
Wraps Adzuna's salary history endpoint to expose time-series compensation data, allowing AI assistants to analyze salary trends without computing historical aggregations. Supports configurable time windows (up to 24 months) and contextual filtering for trend analysis of specific job markets.
Provides pre-computed historical salary trends via API rather than requiring manual collection and aggregation of historical job data; enables trend analysis without maintaining historical job listing archives.
top employer discovery by hiring volume
Medium confidenceQueries Adzuna API to identify and rank companies by number of open job positions within a country, with optional filtering by keywords, location, and category. Returns structured company data including company name and open position count, enabling AI assistants to identify major employers, understand hiring concentration, and help users target high-growth companies.
Exposes Adzuna's top companies endpoint through MCP, enabling AI assistants to identify major employers by hiring volume without fetching and aggregating individual job listings. Supports contextual filtering to discover employers in specific job markets.
Provides pre-ranked employer lists via API rather than requiring manual aggregation of job listings by company; more efficient than client-side company deduplication and ranking.
job category enumeration and validation
Medium confidenceRetrieves the complete set of valid job category tags for a specific country from Adzuna API. Returns structured category data (category IDs and labels) enabling AI assistants to validate category filters before executing job searches. This is a prerequisite capability — categories must be fetched first to ensure search queries use valid category tags, preventing failed searches due to invalid category parameters.
Provides country-specific category enumeration as a prerequisite step before job searches, ensuring AI assistants can validate filter parameters and avoid invalid category errors. Caches category data to reduce API calls for repeated searches in the same country.
Eliminates trial-and-error category discovery by exposing valid categories upfront; prevents failed searches due to invalid category parameters compared to approaches that discover categories through search error responses.
mcp protocol server with stdio transport and credential isolation
Medium confidenceImplements a Model Context Protocol (MCP) server using FastMCP framework that exposes Adzuna job search tools via stdio-based transport. The server handles credential management through environment variables (ADZUNA_APP_ID, ADZUNA_APP_KEY), automatically generates tool schemas from Python function signatures, and manages the request-response lifecycle for AI assistant tool invocations. Supports multiple client configurations (Claude Desktop, Cursor, generic MCP clients) through standardized MCP server interface.
Implements MCP server using FastMCP framework with automatic tool schema generation from Python functions, eliminating manual JSON schema definition. Handles credential isolation through environment variables, preventing API keys from appearing in AI assistant context or logs.
Provides MCP protocol binding to Adzuna API with automatic schema generation, reducing boilerplate compared to manual MCP server implementations; isolates credentials from AI assistant prompts unlike direct API integration approaches.
multi-client deployment configuration with environment variable injection
Medium confidenceProvides standardized configuration templates for deploying the MCP server across multiple AI platforms (Claude Desktop, Cursor, generic MCP clients). Configuration uses environment variable injection to pass Adzuna API credentials securely without embedding them in config files. Supports both virtual environment-based execution and direct Python invocation, enabling flexible deployment across different development environments and CI/CD pipelines.
Provides platform-specific configuration templates (macOS, Windows, Linux) with environment variable injection for credential management, enabling secure multi-platform MCP server deployment without embedding secrets in config files.
Uses environment variable injection for credentials rather than embedding them in config files, improving security; provides platform-specific templates reducing configuration errors compared to generic deployment guides.
api version introspection and compatibility checking
Medium confidenceExposes a tool to retrieve the current Adzuna API version, enabling AI assistants and developers to verify API compatibility and identify potential breaking changes. Returns version information that can be logged or compared against known compatible versions, supporting version-aware behavior and debugging of API integration issues.
Provides direct API version introspection through MCP tool, enabling version-aware behavior and compatibility checking without requiring out-of-band API documentation lookups.
Exposes API version as a queryable tool rather than requiring manual API documentation review; enables automated version checking in deployment pipelines.
advanced job search filtering with multi-parameter composition
Medium confidenceSupports complex job search queries by composing multiple filter parameters (keywords, location, salary range, job type, category, posting date, sort order) into a single Adzuna API request. The MCP tool accepts optional filters for full-time/part-time/contract/permanent job types, salary_min/salary_max ranges, max_days_old for recency filtering, and sort_by for result ordering (date, salary, relevance). Filters are combined using AND logic — all specified filters must match for a job to be included in results.
Composes multiple filter parameters into a single Adzuna API request, allowing LLMs to express complex search intent (e.g., 'permanent full-time roles in London paying £60k+, posted in the last week') without requiring multiple sequential searches. The MCP tool validates filter combinations and provides clear error messages if invalid filters are specified.
More powerful than simple keyword search because it enables multi-dimensional filtering; more efficient than client-side filtering because filters are applied server-side at the Adzuna API level, reducing result set size before transmission.
Capabilities are decomposed by AI analysis. Each maps to specific user intents and improves with match feedback.
Related Artifactssharing capabilities
Artifacts that share capabilities with adzuna-job-search-mcp, ranked by overlap. Discovered automatically through the match graph.
Loopcv
Automates job applications, enhances resumes, tracks...
career-ops
AI-powered job search system built on Claude Code. 14 skill modes, Go dashboard, PDF generation, batch processing.
ezJobs
Automated job search and...
CareerDekho
AI-driven career discovery tailored to individual...
adzuna-mcp
MCP server: adzuna-mcp
job-searchoor
MCP server: job-searchoor
Best For
- ✓AI assistants helping job seekers research opportunities across multiple markets
- ✓Recruitment platforms integrating Adzuna data without building direct API clients
- ✓Career coaches analyzing job market trends for clients in supported countries
- ✓Career counselors advising clients on salary negotiations
- ✓Job seekers evaluating offer competitiveness
- ✓Recruiters benchmarking compensation packages against market data
- ✓Developers deploying MCP servers in production environments
- ✓Teams managing multiple MCP server instances with different credentials
Known Limitations
- ⚠Many job listings lack salary data — salary filters will exclude unlisted positions, reducing result set
- ⚠Adzuna free tier has rate limits — high-volume searches may hit throttling
- ⚠Search results limited to 50 per page maximum — deep pagination requires multiple API calls
- ⚠Category tags are country-specific — must call get_categories first to validate tags
- ⚠Histogram data only includes jobs with listed salaries — unlisted positions are excluded, potentially skewing distribution toward higher-paying roles
- ⚠Salary data is annual amounts only — no hourly or contract-rate breakdowns
Requirements
Input / Output
UnfragileRank
UnfragileRank is computed from adoption signals, documentation quality, ecosystem connectivity, match graph feedback, and freshness. No artifact can pay for a higher rank.
Repository Details
About
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 | 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 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 ### Option 1: Install from PyPI (Recommended) ```bash pip install adzuna-mcp ``` Or use `uvx` for isolated execution: ```bash uvx adzuna-mcp ``` ### Option 2: Install from Source ```bash git clone https://github.com/folarinakinloye/adzuna-mcp.git cd adzuna-mcp pip install -e . ``` ### Option 3: Development Setup ```bash 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` ```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): ```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" } } } } ``` ### With Other MCP Clients Run the server directly: ```bash # 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: ```bash 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_categories` first** 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 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](https://developer.adzuna.com/) 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](CONTRIBUTING.md) for guidelines. ## License MIT License - see [LICENSE](LICENSE) for details. ## Acknowledgments - [Adzuna](https://www.adzuna.com/) for providing the job search API - [FastMCP](https://github.com/jlowin/fastmcp) for the MCP framework - [Anthropic](https://www.anthropic.com/) for the Model Context Protocol specification
Categories
Alternatives to adzuna-job-search-mcp
Search the Supabase docs for up-to-date guidance and troubleshoot errors quickly. Manage organizations, projects, databases, and Edge Functions, including migrations, SQL, logs, advisors, keys, and type generation, in one flow. Create and manage development branches to iterate safely, confirm costs
Compare →AI-optimized web search and content extraction via Tavily MCP.
Compare →Scrape websites and extract structured data via Firecrawl MCP.
Compare →Are you the builder of adzuna-job-search-mcp?
Claim this artifact to get a verified badge, access match analytics, see which intents users search for, and manage your listing.
Get the weekly brief
New tools, rising stars, and what's actually worth your time. No spam.
Data Sources
Looking for something else?
Search →