io.github.michalper/mcp-job-search

mcp-job-search

An MCP server that automates the repetitive mechanics around job-hunting with an AI coding assistant, while deliberately not automating the parts that need a human: drafting your CV/cover letter, fact-checking claims against your real history, and submitting an application.

It answers the question that keeps eating a job search's time: "this CV draft looks fine, but did it quietly fabricate something, and is this one specific posting even worth reading?"

Status: early stage. Built for personal use, published because the configurable anti-fabrication linter and application-registry tooling are generically useful beyond one person's job search. All seven tools are working. See CHANGELOG.md for what changed and what was verified live.

How this differs from other job-search MCP servers

A few open-source MCP servers already do job search + CV tailoring (not-boring-resume-mcp, resume-mcp, Workopia MCP, IAM MCP Server, LinkedIn MCP Server, among others). This one targets what they don't:

1. It won't scrape past a bot-detection wall, even quietly. NoFluffJobs, JustJoin.it and similar Polish IT boards have no public search API — fetch_job_posting reads one URL you already found instead of indexing their listings, and on boards confirmed to sit behind an active Cloudflare challenge (Pracuj.pl, Indeed), it fails loudly rather than trying to solve the challenge automatically. See the verified coverage table below — this is a documented boundary, not a silent gap.
2. The anti-fabrication linter is a configurable rules engine, not hardcoded prose. None of the surveyed alternatives ship a way to enforce your own banned-phrase list, achievement-weight rules, or required clauses — lint_cv reads them from a YAML file you control, so the mechanism is reusable even though the facts it checks against are personal (see "Why a configurable linter" below).
3. It doesn't draft or fact-check for you, on purpose. Writing the CV/cover-letter text and adversarially verifying every claim traces back to something true stays with whatever AI assistant calls these tools — this server is a mechanics layer (search, fetch, render, lint, log), not a weaker bundled LLM call duplicating judgment the calling assistant already does better with full context.

What this server doesn't pretend to be: it doesn't cover every job board — only ones with a real API, or a single posting URL a human already found. It never submits anything on your behalf. And a clean lint_cv run doesn't mean a CV is honest, only that it passes the specific rules you wrote — semantic fabrication (two true facts combined into a false-sounding one) still needs a human or an independent adversarial review to catch.

Install

From PyPI (published as mcp-job-search-mp — mcp-job-search was already taken by an unrelated project; the command stays mcp-job-search):

pip install mcp-job-search-mp
# or, for an isolated tool install:
uvx mcp-job-search-mp

From source, for development:

git clone https://github.com/michalper/mcp-job-search.git
cd mcp-job-search
python3.12 -m venv .venv
.venv/bin/pip install -e ".[dev]"

Connecting to Claude Code

{
  "mcpServers": {
    "job-search": {
      "command": "/absolute/path/to/mcp-job-search/.venv/bin/mcp-job-search",
      "env": {
        "LINT_RULES_PATH": "/absolute/path/to/your/lint_rules.yaml",
        "REGISTRY_CONFIG_PATH": "/absolute/path/to/your/registry.yaml"
      }
    }
  }
}

Configure via environment variables — all optional, every tool degrades gracefully when something is unset:

Adzuna and JSearch free-tier limits

Adzuna's free tier is 25 one-time test calls, then a paid plan (£8/month, 5,000 calls) — budget calls accordingly once past testing. JSearch's free tier is 200 requests/month; search_jobs caches results by query (SEARCH_CACHE_DIR/SEARCH_CACHE_TTL_SECONDS, default 6h) specifically to protect that quota from repeated identical queries — pass use_cache=False to force a fresh one when you actually need it.

Sites behind active bot-detection

fetch_job_posting will never try to solve a CAPTCHA or bot-detection challenge automatically, on any site, regardless of how narrow the request — confirmed via response headers that Pracuj.pl and Indeed (pl.indeed.com) both sit behind an active Cloudflare challenge (cf-mitigated: challenge / 401 with a Cloudflare bot-management cookie), not just a missing-JavaScript issue. A real, human-driven browser session passes both normally — for a page like this, read it with a real browser instead of this tool.

Example: catching a CV the way lint_cv sees it

The CV draft here (tests/fixtures/sample_cv_with_violations.html) was seeded on purpose, and lint_cv is pointed at the bundled generic example rules (src/mcp_job_search/examples/lint_rules.example.yaml), not a real person's facts:

{
  "clean": false,
  "findings": [
    {"severity": "error", "message": "generic corporate jargon — replace with a concrete claim"},
    {"severity": "error", "message": "unsupported superlative — ground it in a specific result or cut it"},
    {"severity": "error", "message": "example: list cloud/K8s here only if you have real production experience"},
    {"severity": "error", "message": "a .gitignore edit is hygiene, not an achievement"},
    {"severity": "error", "message": "a commit count is not an achievement on its own"},
    {"severity": "error", "message": "example: flag a title claim that contradicts your real specialization"},
    {"severity": "note", "message": "link rendered as <a href> in body (https://example.com/portfolio) — use plain text"}
  ]
}

clean is false because real rules fired, not a guess — and every message came from the YAML file, not from code that knows anything about a specific person's career.

Tools

Verified job-board coverage (fetch_job_posting, 2026-10-19)

Why a configurable linter, not a hardcoded one

The original motivation: a CV draft once conflated two separate true facts into one false-sounding claim, and it shipped before anyone caught it. A grep-based mechanical check can catch a banned phrase; it can't catch semantic conflation — that still needs a human or an independent adversarial review. What a mechanical linter can do reliably: enforce your own banned-phrase list, page limits, and required clauses, consistently, every time, without you re-checking the same things by hand. lint_cv is that — generic, so anyone can point it at their own facts.

Development

.venv/bin/python -m pytest --cov     # tests + coverage
.venv/bin/ruff check .               # lint
.venv/bin/mypy src                   # types
.venv/bin/bandit -c pyproject.toml -r src   # security
.venv/bin/pip-audit                  # dependency vulnerabilities

Run .venv/bin/pre-commit install once to run all of the above (except pip-audit, which needs network access and stays CI-only) on every commit.

One manual end-to-end check (not run in CI — needs live network and a real Chrome install), also documented in CHANGELOG.md:

1. search_jobs(keywords="PHP", remote_only=True, sources=["arbeitnow"]) against the live Arbeitnow API.
2. fetch_job_posting(url=...) on a URL from step 1.
3. render_pdf(html_path=...) on a sample CV, confirm success and page_count.
4. lint_cv(html_path=...) on a file with a seeded violation, confirm it's reported.
5. log_application(..., dry_run=True) against your own registry, confirm the previewed row and insertion point look right before dropping dry_run.

See CHANGELOG.md for what changed in each release.

License

MIT — see LICENSE.