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.

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

Tool	Purpose
search_jobs(query, location, tags, source, limit)	Search listings across all sources, ranked by where the terms hit
get_job_details(job_id)	Full listing text for an id from a search or the tracker
save_job(job_id, notes)	Save a listing from the last search into the tracker
add_job(title, company, description, location, url, salary, tags, notes, job_id)	Add a job found elsewhere by pasting its details
set_job_description(job_id, description)	Replace a saved job's description with pasted text
list_saved_jobs(status, limit)	List tracked jobs, newest first
update_job_status(job_id, status, notes)	Move a job through the pipeline
delete_saved_job(job_id)	Remove a tracked job
pipeline_summary()	Counts by status
add_resume(name, text, path)	Store a resume from pasted text or a .md/.txt/.pdf/.docx/.tex file
list_resumes()	Stored resumes, with the default marked
get_resume(name, raw)	Show a resume; raw=true returns the original LaTeX source
set_default_resume(name)	Pick the resume used when a call names none
delete_resume(name)	Remove a resume and its original file
tailor_resume(job_id, resume)	Build the tailoring brief for a job
save_tailored_resume(job_id, content, extension)	Store the tailored CV as LaTeX
get_tailored_resume(job_id)	Read back the tailored CV
tailored_resume_link(job_id)	The tailored CV as a base64 data: URI
list_tailored_resumes()	Every tailored CV written so far
open_web_ui(port)	Start the local browser UI and return its URL

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

Env var	Default	Meaning
JOBFINDER_DB	~/.jobfinder/jobs.db	SQLite file for saved jobs
JOBFINDER_FEED	unset	JSON file for the local source
JOBFINDER_HOME	~/.jobfinder	Base directory for resumes and tailored output
JOBFINDER_RESUME_DIR	$JOBFINDER_HOME/resumes	Where stored resumes live
JOBFINDER_TAILORED_DIR	$JOBFINDER_HOME/tailored	Where tailored resumes are written
JOBFINDER_LATEX_TEMPLATE	built-in template	.tex skeleton used for tailored output