Skip to main content
Glama
jobfinder-mcp

jobfinder-mcp

by juanzjck

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: Job Board MCP Server

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

Available Tools

20 tools
add_jobA

Add a job you found elsewhere (LinkedIn, a referral, an email) to the tracker.

Use this to paste a full job description for a listing that did not come from search_jobs. Reusing an existing job_id overwrites that listing's fields while keeping its application status.

Args: title: role title. company: hiring company. description: full job description text. location: e.g. "Remote", "Berlin". url: link to the original posting. salary: free-form, e.g. "$150,000 - $180,000". tags: comma-separated, e.g. "python, backend". notes: your own notes about the role. job_id: optional explicit id; defaults to a generated "manual:" id.

Inputs: title (required), company (required), url, tags, +5 more. Returns: result

add_resumeA

Store a resume so it can be tailored against job listings.

Give either text (pasted resume) or path (a file to read). Accepted files: .md, .txt, .pdf, .docx, .tex. Non-text files are converted to text for matching and the original is kept so a rewrite can stay in that format. Re-using a name replaces that resume.

Args: name: label for this resume, e.g. "main" or "backend". text: full resume text, if pasting. path: path to a resume file, if uploading.

Inputs: name, path, text. Returns: result

delete_resumeA

Delete a stored resume and its original file.

Inputs: name (required). Returns: result

delete_saved_jobB

Remove a job from the local tracker.

Inputs: job_id (required). Returns: result

get_job_detailsA

Show the full listing for a job id returned by search_jobs or list_saved_jobs.

Inputs: job_id (required). Returns: result

get_resumeB

Show a stored resume. raw returns the original LaTeX source when there is one.

Inputs: raw, name. Returns: result

get_tailored_resumeB

Return the tailored resume stored for a job.

Inputs: job_id (required). Returns: result

list_resumesA

List stored resumes, marking which one is used when none is named.

Inputs: no named parameters. Returns: result

list_saved_jobsA

List saved jobs, newest first, optionally filtered by application status.

Inputs: limit, status. Returns: result

list_tailored_resumesA

List every tailored resume written so far.

Inputs: no named parameters. Returns: result

open_web_uiA

Start the local web UI for browsing saved jobs and their tailored resumes.

Runs on a background thread inside this server, on 127.0.0.1 only, and stops when the MCP client disconnects. Calling it again returns the running URL.

Inputs: port. Returns: result

pipeline_summaryA

Count saved jobs by application status.

Inputs: no named parameters. Returns: result

save_jobB

Save a job from the latest search results to the local tracker.

Inputs: job_id (required), notes. Returns: result

save_tailored_resumeA

Store a tailored resume for a job as LaTeX. Replaces any previous version for that job.

Args: job_id: the job this version targets. content: the full tailored resume, a complete LaTeX document. extension: output file type; leave as "tex" unless you have a reason not to.

Inputs: job_id (required), content (required), extension. Returns: result

search_jobsA

Search job listings.

Args: query: keywords matched against title, tags, company and description. location: substring filter on the listing location (e.g. "remote", "berlin"). tags: comma-separated tags that must all be present on the listing. source: restrict to one source ("remoteok" or "local"); empty means all. limit: maximum listings to return.

Inputs: tags, limit, query, source, +1 more. Returns: result

set_default_resumeA

Choose which resume is used when a tailoring call does not name one.

Inputs: name (required). Returns: result

set_job_descriptionA

Replace the description of a saved job with pasted text.

Useful when the listing was saved from a feed with a truncated or empty description and you have the full text.

Inputs: job_id (required), description (required). Returns: result

tailor_resumeA

Build a tailoring brief: the listing's requirements matched against a stored resume.

Returns the job's must-have and frequent terms split into what the resume already evidences and what it does not, then the resume text, then the LaTeX to write into. Tailored output is always LaTeX: when the stored resume is a .tex file its source is included to rewrite in place, otherwise a template is included to fill. Write the CV, then store it with save_tailored_resume.

Args: job_id: id from search_jobs, add_job or list_saved_jobs. resume: stored resume name; empty uses the default resume.

Inputs: job_id (required), resume. Returns: result

update_job_statusA

Update the application status and/or notes of a saved job.

Valid statuses: saved, applied, interviewing, offer, rejected, archived.

Inputs: job_id (required), notes, status. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 20 tools

    Disambiguation4/5

    Most tools have distinct purposes, but save_job and add_job both create a saved job, which could cause confusion. The descriptions clarify the source, so an agent can differentiate with careful reading.

    Naming Consistency4/5

    Most tools follow verb_noun naming (search_jobs, get_job_details, save_job). However, pipeline_summary and tailored_resume_link are noun-phrase names, breaking the pattern slightly.

    Tool Count3/5

    At 20 tools, this is on the heavier side. The dual purpose (job tracking and resume tailoring) justifies many tools, but it borders on overwhelming for an agent.

    Completeness4/5

    The job lifecycle (search, save, update, delete, summaries) and resume tailoring workflow (add, tailor, save, retrieve) are well covered. Missing a dedicated delete for tailored resumes is a minor gap.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      D
      maintenance
      A local job-hunting MCP server for discovering jobs across pluggable web sources, tracking applications through a status lifecycle, and managing profiles/resumes, with geo/map-region search.
      12
      -
    • A
      license
      A
      quality
      B
      maintenance
      Enables searching and retrieving job listings from multiple platforms through MCP.
      2
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables an MCP-capable coding agent to run a local-first job search: recording verified opportunities in a private SQLite tracker, tracking follow-ups and outcomes, and preparing evidence-based resumes, application answers, and outreach drafts. It keeps all personal data on the user's machine and stops before submitting applications, uploading documents, or contacting anyone.
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables any MCP-capable AI app to act as a personal job-search assistant by storing resumes and job postings, matching skills, tracking applications, and analyzing market skill demand.
      MIT