Job Hunter MCP
Reads Gmail read-only via the Gmail API, classifies recent emails such as rejections, interview/assessment invites, offers, acknowledgements, and scams in multiple languages, and matches them to tracked job applications, optionally applying status updates.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Job Hunter MCP
Let Claude help you find work and keep track of every application, in the UK and across Europe.
Job Hunter is an MCP server. Plug it into Claude Desktop, Claude Code or any MCP client, and you can just say:
"Find temporary jobs near me in logistics."
"Add the one I applied to, to my tracker."
"Any replies in my inbox?"
It has three jobs:
What it does | |
🔎 Search | Searches Reed (UK) and Adzuna (UK + 9 European countries) through their official free APIs. It filters out self-employed, freelance and commission-only roles (in 7 languages), low pay, permanent jobs (optional), duplicates and employers you've already applied to. |
📋 Track | Keeps a local database of applications and exports a colour-coded Excel sheet: 🟦 blue = found, not applied · 🟩 green = applied / interview / offer · 🟥 red = rejected · ⬜ grey = withdrawn. |
📬 Inbox | Reads your Gmail read-only, flags rejections, interview/assessment invites, offers, acknowledgements and scams (like fake "loan approved" emails) in 8 languages, and matches them to the employers you're tracking. |
Everything stays on your computer. Nothing is sent, deleted or applied for on your behalf.
Tools
Tool | Purpose |
| Search Reed and Adzuna. Arguments: keywords, location, country, distance (miles or km), temp-only, minimum hourly pay, and whether to hide employers you already track. |
| Add a job with status |
| Change the status and add a dated note. |
| See everything, or filter by status, with counts. |
| Delete a duplicate. |
| Write the colour-coded |
| Classify recent emails and match them to applications. Optionally apply the status changes automatically ( |
Related MCP server: jobfinder
Install
Requires Python 3.10+.
git clone https://github.com/YounesDjellikh/job-hunter-mcp.git
cd job-hunter-mcp
pip install -e ".[gmail]" # drop [gmail] if you don't want the inbox check1. Get free API keys
Reed: https://www.reed.co.uk/developers/jobseeker (instant, free)
Adzuna: https://developer.adzuna.com/ (free app id + key)
You only need one of them. The more you add, the more jobs you'll see.
2. Configure
mkdir -p ~/.job-hunter
cp config.example.yaml ~/.job-hunter/config.yamlEdit ~/.job-hunter/config.yaml with your default location, filters and (optionally) keys. Or keep keys out of files completely with environment variables: REED_API_KEY, ADZUNA_APP_ID and ADZUNA_APP_KEY.
3. Connect it to Claude
Claude Desktop: add this to claude_desktop_config.json (see examples/claude_desktop_config.json):
{
"mcpServers": {
"job-hunter": {
"command": "job-hunter-mcp",
"env": { "REED_API_KEY": "your-key" }
}
}
}Claude Code:
claude mcp add job-hunter -e REED_API_KEY=your-key -- job-hunter-mcpRestart Claude and ask it to search for jobs.
🇪🇺 Using it outside the UK
Country | Code | Job sources | Currency |
🇬🇧 United Kingdom |
| Reed + Adzuna | GBP |
🇫🇷 France |
| Adzuna | EUR |
🇩🇪 Germany |
| Adzuna | EUR |
🇪🇸 Spain |
| Adzuna | EUR |
🇮🇹 Italy |
| Adzuna | EUR |
🇳🇱 Netherlands |
| Adzuna | EUR |
🇧🇪 Belgium |
| Adzuna | EUR |
🇦🇹 Austria |
| Adzuna | EUR |
🇨🇭 Switzerland |
| Adzuna | CHF |
🇵🇱 Poland |
| Adzuna | PLN |
Get a free Adzuna key (Reed is UK-only).
In
config.yaml, setsearch.country,search.locationandsearch.distance_km. There are ready-made examples inexamples/config.france.yamlandexamples/config.germany.yaml.Search with local-language keywords for the best results: "préparateur de commandes", "Lagerhelfer", "mozo de almacén", "magazziniere", "orderpicker", "magazynier".
You can switch country for a single search: "search_jobs: keywords='Lagerhelfer', location='Hamburg', country='de'".
Email checks understand English, French, German, Spanish, Italian, Dutch, Polish and Portuguese. For example, "Malheureusement…", "Leider…", "Lamentablemente…", "Purtroppo…", "Helaas…" and "Niestety…" are all recognised as rejections. A job advert that mentions a "permanent contract" is not mistaken for a job offer.
Self-employment filter: by default it drops roles mentioning auto-entrepreneur, indépendant, selbstständig, Freiberufler, autónomo, partita IVA, ZZP, samozatrudnienie and their equivalents.
Gmail setup (optional)
The inbox check uses your own Google OAuth client with the read-only scope (gmail.readonly).
Go to https://console.cloud.google.com/, create a project, and enable the Gmail API.
Under APIs & Services → OAuth consent screen, choose External and add yourself as a test user.
Under Credentials → Create credentials → OAuth client ID, choose Desktop app. Download the JSON.
Save it as
~/.job-hunter/credentials.json.The first time you run
check_inbox, a browser window asks you to approve read-only access. The token is saved to~/.job-hunter/token.json.
Revoke access at any time at https://myaccount.google.com/permissions.
Good to know
Official APIs only. No scraping, no logging into job boards with your password, no auto-applying. You still submit every application yourself. The agent finds and tracks.
Your data is local. The tracker lives in
~/.job-hunter/tracker.db.config.yaml,credentials.json,token.json,*.dband*.xlsxare git-ignored, so they can't be committed by accident.Email classification is keyword-based, so check anything important yourself. Recruiters word rejections in creative ways ("we won't be moving forward", "on this occasion…"). If one slips through, add the phrase to
RULESingmail.pyand open a PR.Self-employed roles are hidden by default via
exclude_keywords. Remove those keywords inconfig.yamlif you want to see them.
Development
pip install -e ".[dev,gmail]"
pytestPRs welcome, especially:
new job sources with official APIs, e.g. France Travail (France), Bundesagentur für Arbeit (Germany), Totaljobs and CV-Library (UK);
more countries and languages;
better email rules: if a real rejection or invite slipped through, add the phrase to
RULESingmail.py, with a test.
License
MIT © 2026 Younes Djellikh
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Job search tracker for Claude and ChatGPT: applications, interviews, follow-ups, company watch.
Track job applications on a board: let Claude or ChatGPT read and update jobs, interviews, notes.
Analyze job listings against your resume, track applications, and generate cover letters.
Your career companion for ATS checks, resumes, cover letters, job tracking, websites, and more.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables Claude to parse CVs, search job boards (Remotive, Arbeitnow, Adzuna, Greenhouse/Lever), tailor resumes and cover letters, and prepare application packages with direct apply links—without ever auto-submitting. It runs 100% locally and free, storing jobs and applications as JSON files.-
- AlicenseNot gradedqualityDmaintenanceEnables AI-powered job searching across multiple platforms using natural language or CV uploads, ranking results by shortlisting likelihood and generating detailed spreadsheets. Integrates with Claude to perform full job searches, preview query interpretation, and manage platform configurations.MIT
- AlicenseNot gradedqualityBmaintenanceEnables Claude to read and update the local job-search tracker, adding postings from screenshots, pasted text or links, drafting application emails, syncing Gmail to log sent applications and replies, and answering questions about what's due or which jobs match a criteria. Every change is validated and appears live on the dashboard with a timeline entry.MIT
- AlicenseBqualityBmaintenanceEnables Claude to search job listings on selected sites, filter and score them against your own skills, track application status, and generate a tailored LaTeX/PDF resume for each job. It also supports importing an existing Word or PDF resume and diagnosing local setup, all with data kept in a private folder on your own machine.12MIT