jobfinder-mcp

A local MCP server for searching job listings and tracking applications. Runs entirely on your machine over stdio; saved jobs live in a local SQLite file.

Install

python3 -m venv .venv
.venv/bin/pip install -e .

Requires Python 3.10+. The SDK is pinned to mcp>=1.2,<2: mcp 2.x removed mcp.server.fastmcp, which this server is built on.

Related MCP server: witness-mcp

Run

.venv/bin/jobfinder-mcp          # or: .venv/bin/python -m jobfinder_mcp

The server speaks MCP over stdio, so running it by hand just blocks waiting for a client. To inspect it interactively:

.venv/bin/mcp dev src/jobfinder_mcp/server.py

Web UI

.venv/bin/jobfinder-web            # http://127.0.0.1:8765, opens a browser
.venv/bin/jobfinder-web --port 0 --no-browser

Two panes: tracked jobs on the left (search box, status filters, a badge showing the tailored resume's file type), the selected job on the right with tabs for the full Description and its Tailored resume — copy it, download the file, or take it as a self-contained data:application/x-tex;base64,… link (shown under the buttons, with copy data URI next to it). The whole document lives inside that link, so it can be pasted anywhere and downloaded with this server stopped.

For .tex output there is also Open in Overleaf, which POSTs that data URI to overleaf.com/docs as snip_uri and opens the compiled CV in a new tab — the way to get a PDF without a local TeX install. It uploads the resume to Overleaf, so it only fires when you click it. Note that Chrome refuses data: URIs typed into the address bar; only the in-page controls work. The status dropdown writes straight back to the tracker, so the MCP tools and the UI stay in sync; hit refresh after Claude saves something new.

It reads the same SQLite file and tailored directory as the MCP server, and binds to loopback only — it serves your resume and application notes, so do not expose it on a LAN interface. The MCP tool open_web_ui(port) starts the same UI on a background thread inside the running server.

Register with Claude Code

claude mcp add jobfinder -- /Users/juansalzar/Documents/git/jobfinder/.venv/bin/jobfinder-mcp

Or add it to ~/.claude.json / .mcp.json manually:

{
  "mcpServers": {
    "jobfinder": {
      "command": "/Users/juansalzar/Documents/git/jobfinder/.venv/bin/jobfinder-mcp"
    }
  }
}

For Claude Desktop, the same block goes in ~/Library/Application Support/Claude/claude_desktop_config.json.

Tools

Resource jobfinder://saved returns every tracked job as JSON. Prompt tailor_application(job_id, resume_summary) drafts a cover letter; with no resume_summary it uses the default stored resume.

Statuses: saved, applied, interviewing, offer, rejected, archived.

Tailoring a resume

The server does not call an LLM. tailor_resume returns a brief — the listing's must-have terms, its most frequent terms, and which of them the resume already evidences — and the model driving the client writes the CV from it. Nothing is sent anywhere, and there is no API key or per-call cost.

add_resume(name="main", path="~/Documents/cv.pdf")
search_jobs(query="python backend", location="remote")
save_job(job_id="remoteok:123456")
tailor_resume(job_id="remoteok:123456")      # -> brief; the model writes the CV
save_tailored_resume(job_id="remoteok:123456", content="\\documentclass...")

PDF, DOCX and LaTeX files are converted to text for matching, and the original is kept next to it. A scanned, image-only PDF extracts to nothing; paste the text with add_resume(name, text=...) instead.

LaTeX output

Tailored resumes are always written as .tex. tailor_resume ends its brief with the LaTeX to write into:

• the stored resume is a .tex file → its source is included, to be rewritten in place with the preamble, macros and layout left alone;

• otherwise → a plain article-class template is included for the model to fill.

save_tailored_resume rejects content with no \documentclass or \begin{document}; pass an explicit extension to store another format anyway. There is no LaTeX toolchain in this project — compile the result with pdflatex/tectonic, or upload it to Overleaf.

To use your own layout instead of the built-in template, drop a .tex file at ~/.jobfinder/resume_template.tex or point JOBFINDER_LATEX_TEMPLATE at one.

Term matching is deterministic string work: known multi-word phrases plus non-stopword tokens, normalized through an alias table so k8s in a listing matches Kubernetes in a resume. It surfaces gaps; it does not judge fit.

Sources

• remoteok — RemoteOK's public JSON feed. No API key. Cached 15 minutes.

• local — set JOBFINDER_FEED=/path/to/jobs.json to read your own listings. The file is a JSON list of objects with at least id, title and company; location, url, salary, tags, description are optional.

Add another source by writing a fetch_* function in sources.py that returns normalized job dicts, then registering it in the SOURCES map.

Configuration