mcp-job-search

An MCP server that finds recent job postings based on your LinkedIn profile, scores each against your resume, and logs the results — all without logging into or scraping LinkedIn.

Why no LinkedIn scraping? LinkedIn's User Agreement prohibits automated access, and scraping risks your account. Instead this server reads search terms from a LinkedIn export you download, and pulls listings from the JSearch API, which aggregates postings (including LinkedIn's) via Google for Jobs.

How it works

LinkedIn export (CSV or PDF)  ->  search terms
                                      |
                              JSearch API (last week)
                                      |
                 filter to LinkedIn + drop already-seen
                                      |
              score vs resume (weighted skill coverage)
                                      |
            logs/matches-*.log  +  reports/job_match-*.html

Tools

Tool	What it does
get_profile_terms	Show the search terms derived from your LinkedIn export + the queries that will run.
search_jobs	Search all profile queries (default: last week), de-dupe, return new postings, write a log.
match_jobs	Like search_jobs, plus fetch each job's full description and score it against your resume (weighted skill-coverage %, knockout penalties), ranked best-fit first. Writes a text log and a styled HTML report.
search_jobs_custom	Run a single ad-hoc query.
reset_seen_jobs	Forget previously-seen jobs so the next run shows everything again.

---

Setup (step by step)

1. Install

git clone https://github.com/rajivdatta/mcp-job-search.git
cd mcp-job-search
python -m venv .venv
.venv\Scripts\activate          # Windows  (use: source .venv/bin/activate on macOS/Linux)
pip install -r requirements.txt

2. Get a JSearch API key (free)

1. Create a RapidAPI account → https://rapidapi.com/auth/sign-up
2. Open the JSearch API → https://rapidapi.com/letscrape-6bRBa3QguO5/api/jsearch
3. Click Subscribe to Test (or the Pricing tab) and choose the Basic / Free plan → Subscribe.
4. On the Endpoints tab, the right-hand code panel shows a header X-RapidAPI-Key: <your-key>. Copy that key.

3. Create your .env

Copy .env.example to .env and paste your key:

RAPIDAPI_KEY=your-rapidapi-key-here

.env is git-ignored — your key never leaves your machine.

4. Provide your LinkedIn profile

Either form works (CSV is more precise; PDF is quicker):

• CSV export — LinkedIn → Settings → Data Privacy → Get a copy of your data → include Profile, Positions, Skills → download and extract the ZIP into a folder.
• PDF — your profile page → More → Save to PDF. Drop the PDF into a folder.

The server reads your most-recent titles, headline, and top skills to build search queries.

5. Create your config.json

Copy config.example.json to config.json and edit it:

{
  "linkedin_export_dir": "C:\\path\\to\\LinkedInExport",  // folder with your CSV export or PDF
  "resume_path":         "C:\\path\\to\\resume.pdf",      // .pdf or .txt, used by match_jobs
  "location":            "Toronto, Ontario, Canada",       // appended to each query
  "country":             "ca",                             // JSearch 2-letter country code
  "date_posted":         "week",                           // today | 3days | week | month
  "num_pages":           1,                                // JSearch pages per query (~10 jobs/page)
  "max_queries":         3,                                // how many profile titles to search
  "log_dir":             "logs",                           // where text logs are written
  "query_override":      [],                               // set explicit queries to skip profile parsing
  "only_linkedin":       true,                             // keep only LinkedIn-sourced postings
  "only_new":            true                              // across runs, return only jobs not seen before
}

Config field reference

Field	Required	Notes
linkedin_export_dir	for profile-based search	Folder containing your LinkedIn CSV export or a profile PDF.
resume_path	for match_jobs	Path to your resume (.pdf or .txt).
location	recommended	Free-text location appended to each query, e.g. "Toronto, Ontario, Canada".
country	recommended	JSearch country code (ca, us, gb, …).
date_posted	optional	Recency window: today, 3days, week (default), month.
num_pages	optional	Pages fetched per query; each page ≈ 10 jobs. Higher = more results + more API usage.
max_queries	optional	Caps how many profile-derived titles are searched (to limit API calls).
log_dir	optional	Directory for text logs (default logs).
query_override	optional	A list of explicit query strings. If non-empty, profile parsing is skipped and these are used verbatim.
only_linkedin	optional	true keeps only postings whose source is LinkedIn.
only_new	optional	true remembers shown jobs (in state/seen_jobs.json) and returns only unseen ones on later runs.

6. Test it standalone

.venv\Scripts\activate
python -c "import json, server; print(server.get_profile_terms())"   # check derived queries
python -c "import json, server; print(server.match_jobs())"          # live search + match

Outputs land in logs/ and reports/.

7. Register with your MCP host

Add a server entry pointing at the venv's Python and server.py (see examples/mcp.json):

{
  "mcpServers": {
    "job-search": {
      "command": "C:\\path\\to\\mcp-job-search\\.venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\mcp-job-search\\server.py"],
      "env": { "RAPIDAPI_KEY": "your-key-or-leave-it-in-.env" }
    }
  }
}

Restart your MCP client, then try: "using job-search, match jobs".

Use with Claude Desktop

Claude Desktop reads its MCP servers from claude_desktop_config.json. Open it from Settings → Developer → Edit Config (this creates the file if it doesn't exist), or edit it directly:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Add this server under mcpServers, using absolute paths to the venv's Python and server.py (the key can stay in .env instead of env):

{
  "mcpServers": {
    "job-search": {
      "command": "C:\\path\\to\\mcp-job-search\\.venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\mcp-job-search\\server.py"],
      "env": { "RAPIDAPI_KEY": "your-key-or-leave-it-in-.env" }
    }
  }
}

On macOS the paths are POSIX, e.g. "command": "/Users/you/mcp-job-search/.venv/bin/python". Save the file and fully quit and reopen Claude Desktop (use Quit from the tray/menu-bar icon — closing the window isn't enough). The server's tools then appear in the tools (🔌) menu of a new chat.

---

Scheduling (optional)

To run the search automatically each day, use the included helpers — they call the same match_jobs logic directly, so no MCP host needs to be running:

• run_daily.py — runs match_jobs, writes the report/log, appends a status line to logs/daily_runs.log.
• run_daily_hidden.vbs — launches run_daily.py via the venv Python with no console window (self-locating; works from any folder).
• setup_schedule.ps1 — registers a Windows Scheduled Task.

# from the repo folder, after creating .venv and installing requirements:
.\setup_schedule.ps1               # daily at 16:00 (4 PM)
.\setup_schedule.ps1 -At "08:30"   # custom time

The task runs when you're logged on. To run while logged off, enable "Run whether the user is logged on or not" in Task Scheduler (stores your password). Remove it with Unregister-ScheduledTask -TaskName "MCP Job Search Daily".

On macOS/Linux, schedule python run_daily.py with cron instead.

Dedupe across runs

With only_new: true, search_jobs and match_jobs remember every posting they show (in state/seen_jobs.json) and return only postings you haven't seen on later runs. Each result reports total_found, new_jobs, and suppressed_already_seen. Pass only_new=false to a single call to see the full list once, or call reset_seen_jobs to clear the memory.

Matching (how the score works)

match_jobs detects known skills in the job description and your resume, then scores weighted coverage = (weighted skills you have that the job asks for) / (weighted skills the job asks for), with:

• core skills weighted higher than peripheral ones,
• a denominator floor so sparse ads can't auto-score 100%,
• a knockout penalty when a specialized must-have (e.g. SAS, Workday, Salesforce Data Cloud) is required but missing.

Each job reports matched_skills, missing_skills, and knockouts_missing, so the number is explainable. It's a fast first pass — it does not model seniority or non-skill credential gates. Tune the skill sets and constants at the top of match.py.

Output & privacy

• logs/ — text logs of each search/match run
• reports/job_match_<date>.html — a cumulative styled match report per day. Re-running on the same day merges in new matches and keeps earlier ones; the latest run's additions are flagged NEW (so a second run never shrinks it).
• state/seen_jobs.json — the all-time dedupe memory
• state/results_<date>.json — today's accumulated matches (backs the cumulative report)

.env, config.json, logs/, reports/, state/, and the export folder are all git-ignored — nothing personal is committed.

License

MIT