mcp-job-search

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