Job Search Assistant — MCP Server

A local Model Context Protocol server that lets Claude read and update your job-search spreadsheets through natural conversation — "what's still awaiting a response after 2 weeks?", "add this posting to my tracker", "mark the Amazon role as interviewing", "add a Salary Range column and set it to 180-210k for the Amazon role", "what remote leads did I find this week?", "promote the Acme Corp lead to my tracker".

It manages a funnel — discover → apply → track — plus an interview-prep note:

promote_to_tracker turns a discovery lead into a tracked application; save_document and print_document write generated docs to the Resumes\ folder and print them. An optional Gmail integration (five tools) searches your inbox for recruiter mail, scans for updates on tracked roles, and drafts/sends replies — see Gmail integration.

• Runtime: Node.js + TypeScript

• Transport: stdio (local process — no networking, no auth)

• Data source: your .xlsx files, read/written with SheetJS (xlsx)

• Schema: dynamic — driven by each sheet's header row (custom columns supported)

• Printing: silent PDF printing via pdf-to-printer (bundles SumatraPDF); .docx is converted to PDF first using LibreOffice or Microsoft Word

• Client: Claude Desktop or Claude Code (see config below)

Build

cd mcp-job-tracker
npm install
npm run build

This produces dist/index.js. npm install also pulls pdf-to-printer, which bundles SumatraPDF for silent PDF printing (no separate install). Printing .docx additionally requires LibreOffice or Microsoft Word for the docx→PDF conversion step; PDFs need neither. Keeping the discovery sheet's formatting on MCP writes uses Python + openpyxl (scripts/format_discovery.py); optional — writes still succeed without it. generate_resume needs Python + python-docx (scripts/gen_resume.py) plus LibreOffice (matches the existing resumes' look) for its PDF step. read_document uses Python + pypdf (PDFs) and python-docx (docx) via scripts/extract_text.py. The optional Gmail tools need a one-time npm run gmail:auth (see Gmail integration).

Related MCP server: quantjobs

Configure Claude Desktop

Open Claude Desktop's config file (Windows):

%APPDATA%\Claude\claude_desktop_config.json

Add a job-tracker server entry (create the file / mcpServers object if needed):

{
  "mcpServers": {
    "job-tracker": {
      "command": "node",
      "args": ["C:\\Users\\developer\\mcp-job-tracker\\dist\\index.js"],
      "env": {
        "JOB_TRACKER_FILE": "C:\\Users\\developer\\Documents\\Job_Tracking.xlsx",
        "JOB_DISCOVERY_FILE": "C:\\Users\\developer\\Documents\\Job_Search_Discovery.xlsx",
        "JOB_INTERVIEW_PREP_FILE": "C:\\Users\\developer\\Documents\\Interview_Prep_QA.md",
        "JOB_RESUMES_DIR": "C:\\Users\\developer\\Documents\\Resumes"
      }
    }
  }
}

Restart Claude Desktop. You should see the job-tracker tools appear. If JOB_TRACKER_FILE is omitted, the server defaults to <home>\Documents\Job_Tracking.xlsx. If JOB_DISCOVERY_FILE, JOB_INTERVIEW_PREP_FILE, or JOB_RESUMES_DIR are omitted, they default to Job_Search_Discovery.xlsx, Interview_Prep_QA.md, and a Resumes\ folder sitting **next to** the tracker file. **Claude Code** uses the same entry under mcpServers in ~/.claude.json.

Moving to another machine

The server is portable (plain Node stdio — Windows or macOS). To set it up on a new machine:

1. Copy this project folder over (you can skip node_modules and dist).

2. Copy your Job_Tracking.xlsx to the new machine.

3. Make sure Node.js 18+ is installed (node --version).

4. Run the installer, pointing it at your spreadsheet:

   node setup.mjs "C:\\path\\to\\Job_Tracking.xlsx"     # Windows
   node setup.mjs "/Users/you/Documents/Job_Tracking.xlsx"  # macOS

   It installs deps, builds, backs up the existing Claude Desktop config, and wires in the job-tracker entry with paths correct for that machine. Omit the path to default to <home>/Documents/Job_Tracking.xlsx. Flags: --no-build (reuse a copied dist/), --bare-node (use node from PATH instead of an absolute node path).

5. Fully quit and restart Claude Desktop.

Tools

Discovery-sheet tools (Job_Search_Discovery.xlsx)

Interview-prep tools (Interview_Prep_QA.md)

Document tools (Resumes\)

Gmail tools (optional — require one-time auth)

Until Gmail is authorized (see Gmail integration below), all five return a clear "authorize first" error.

Spreadsheet schema

Both workbooks use a dynamic schema — the columns are driven by each sheet's actual header row, and the read/write engine is schema-agnostic (a sheet is just a spec: file path, required columns, which columns are dates, and the match keys).

Tracker (Job_Tracking.xlsx)

The ten base columns below must always be present (the tools match, filter, and compute dates on them) and are protected from rename/delete:

Company | Position | Job Link | Location | Resume Version | Contact/Referral | Date Applied | Status | Next Follow-Up | Notes

Any custom columns you add beyond these are first-class:

• They appear in list_jobs / get_job output automatically.

• You set them per job with the extra_fields argument of add_job and update_job, e.g. extra_fields: { "Salary Range": "180-210k" } (an empty string clears the value).

• You add / rename / remove them with add_column, modify_column, and delete_column.

Custom columns are stored as text. The two base date columns (Date Applied, Next Follow-Up) are the ones stored as Excel date serials.

Managing columns

// add a column, pre-filled on every existing row
add_column      { "name": "Salary Range", "default_value": "TBD" }
// rename it and/or overwrite every row's value
modify_column   { "name": "Salary Range", "new_name": "Comp", "fill_value": "Confidential" }
// remove it (shifts later columns left, like Excel)
delete_column   { "name": "Comp" }

Conventional Status values: Applied, Awaiting Response, Informal - Referral Sent, Interviewing, Offer, Declined, Withdrawn, Closed - No Longer Available. (The field is free text — these are just the values suggested to Claude.)

Discovery (Job_Search_Discovery.xlsx)

The base columns, in order:

Date Found | Company | Position | Location (Remote/Hybrid) | Salary | Salary Confidence (Confirmed/Estimated) | Job Link | Source (Company Careers Page/LinkedIn/Aggregator) | Posted Date / Days Since Posted | Known Gap Flag | Match Assessment | Status

All discovery values are stored as text (including Date Found, kept as an ISO YYYY-MM-DD string — no date-serial conversion). Rows are matched by Company + Position. Set columns through the fields argument of discovery_add / discovery_update; Company and Position have their own parameters. Status on new leads defaults to Open.

The column-management tools (add_column etc.) operate on the tracker; the discovery sheet is managed through its own row tools.

Formatting: the discovery sheet is also written by the daily 11 AM task (Python + openpyxl, with bold header / frozen row / auto-filter / clickable links). Because SheetJS (used by the MCP tools) doesn't re-serialize that rich styling, every MCP discovery write is followed by a best-effort openpyxl reformat pass (scripts/format_discovery.py) that re-applies the standard formatting — so MCP edits and the daily task keep the file looking the same. Requires Python + openpyxl; if absent, the write still succeeds (the tool returns formatted: false) and the next daily run restores styling.

Interview prep (Interview_Prep_QA.md)

A plain-markdown reference — not a spreadsheet — organised as:

# Interview Prep — Q&A Reference

## Company — Role
**Q: ...?**

A: ...

*Notes: ...*

---

## Next Company — Role
...

append_interview_prep matches an existing ## Company section on the company portion of the heading (the part before — Role), so appending "Acme Corp" lands under ## Acme Corp — Engineering Manager. New sections are separated with ---. Keep to the **Q: …** / A: … / optional *Notes: …* pattern when adding content.

If a bare company name matches more than one section (e.g. ## Acme Corp — Billing and ## Acme Corp — Clinical), both read/append refuse and list the matches — pass the full heading to disambiguate. An exact full-title match always wins over a bare prefix, so a specific heading is never ambiguous.

Generating a tailored resume (generate_resume)

The recommended way to produce a resume — especially from Claude Desktop, which can't write to arbitrary host paths. The model never emits the binary; it emits tailored text, and the server renders the PDF host-side. The server's MCP instructions tell connected clients to use this tool for resumes rather than hand-rolling a python-docx/LibreOffice script or moving bytes through base64, so it's the single resume path (scripts/gen_resume.py is the one generator).

generate_resume {
  "company": "Acme Corp",
  "position": "Engineering Manager",
  "summary": "…tailored SUMMARY paragraph for this posting…",
  "key_qualifications": [
    "…bullet tying real experience to this role…",
    "…another alignment bullet…"
  ]
  // optional: skills[], include_projects, format ("pdf"|"docx"), filename, overwrite
}

• Facts stay fixed. Employers, titles, dates, education, certs, and the base skills live in resume_master.json; the model can't invent or drift them — it only supplies the summary and key_qualifications for this company + position. Edit your real facts in resume_master.json (a sibling of the tracker; override with JOB_RESUME_MASTER_FILE).

• Rendering merges master + tailoring → .docx via scripts/gen_resume.py (python-docx, the measured spec: Liberation Serif, 20 pt name, ruled 11 pt headings, 0.63" margins, US Letter) → PDF via LibreOffice. ~15 s per resume.

• Output lands in Resumes\ (e.g. Dale-Magrath-Resume-Acme-Corp-Engineering-Manager.pdf), ready for print_document. No base64, no download-then-move.

• Wired to tracking. The result carries a nextStep with the exact follow-up call, chosen from the sheets: brand-new company → add_job (as Applied, Resume Version set to the file), an existing discovery lead → promote_to_tracker, already tracked → update_job to set the Resume Version. So tailor → save → apply → track is one Desktop flow — the model just offers the suggested step.

Why this beats base64: the tailored text is ~1 k tokens; the 55 KB PDF binary would be ~22 k. The model does the writing; the host does the rendering.

Rendering notes (why it's built this way)

Hard-won details worth keeping — changing them tends to reintroduce old bugs:

• Role/date lines are a 2-column borderless table, not a tab stop. A tab with a right tab-stop spanning a bold title and italic dates in one paragraph triggered a LibreOffice PDF-export bug (ToUnicode CMap on subset fonts) that made the title extract as garbled characters in pdftotext, pypdf, and pdfminer.six — even though it looked fine on screen (and could trip ATS parsers). The table renders identically and extracts cleanly in all three. Keep it a table.

• LibreOffice does the docx→PDF, not Word. LibreOffice subsets fonts → ~55 KB with Liberation Serif, matching the existing resumes. Word barely subsets (embedded ~1.1 MB of Calibri → a 258 KB PDF), so convertDocxToPdf prefers LibreOffice and falls back to Word only if it's absent.

• 2-page fit is by layout, never by truncation. A full experience history + 6-bullet Key Qualifications + Projects + Education + Skills lands on 2 pages with Honors & Awards off (opt in with include_honors). If it ever runs long, the lever is tightening spacing (heading 12/5 pt, body 8 pt) — content is never silently trimmed to hit a page count.

• base64 is a last resort. The only resume ever saved through the base64 path came out corrupt (valid %PDF/%%EOF but a broken startxref). The leading-bytes check catches gross truncation, not subtle corruption — so prefer generate_resume, or save_document with source_path, for anything binary.

Saving an already-generated document (Resumes\)

If a file already exists on disk (e.g. produced by the docx/pdf skill), save_document puts it into Resumes\, and print_document sends it to a printer:

// Preferred: hand over a path to a file already written to disk.
save_document   { "filename": "Dale-Resume-Acme-Corp.docx", "source_path": "C:\\Temp\\out.docx" }
print_document  { "filename": "Dale-Resume-Acme-Corp.docx" }            // default printer
print_document  { "filename": "sample.pdf", "printer_name": "Office EPSON ET-3850 Series" }

Always prefer source_path for real documents. content_base64 makes the model emit the whole file as base64 token-by-token — roughly 3 characters per token for binary formats, so a 53 KB resume is ~22 000 output tokens (several minutes), and a 134 KB PDF exceeds the response limit and can never finish. source_path costs ~30 tokens at any file size and can't corrupt the bytes. Inline base64 is therefore capped at 20 000 characters and fails immediately with a pointer to source_path.

• PDFs print directly via SumatraPDF (bundled with pdf-to-printer); no dialog, single copy, default settings.

• .docx is converted to a PDF next to it first — using LibreOffice (soffice --headless --convert-to pdf) if installed, otherwise Microsoft Word via COM. The PDF is cached and reused while it's newer than the docx. If neither LibreOffice nor Word is available, printing a .docx returns a clear error suggesting you save it as a PDF instead.

• print_document confirms the job was sent to the printer — not that it physically finished. Base64 transport is meant for small files (resumes, well under 1 MB), not large documents.

Gmail integration (optional)

The five Gmail tools let Claude search your inbox for recruiter mail, scan for updates on tracked applications, and draft/send replies — all against your own account. They're off until you authorize them; unauthorized calls return a clear error telling you what to run.

One-time setup (full walkthrough in GMAIL_SETUP.md):

1. Create a Google Cloud project, enable the Gmail API, and create a Desktop app OAuth client; download its JSON as credentials.json in the project root (next to package.json). This step is manual — it can't be scripted.

2. Run the one-time consent flow:

   npm run gmail:auth

   It opens Google's consent screen and saves the token to gmail_token.json. The server refreshes it automatically afterward.

3. Restart Claude Desktop so the tools load.

Config / files (both .gitignored):

Requested scopes are read-only + compose + send (gmail.readonly, gmail.compose, gmail.send) — intentionally no mailbox modify/delete access. npm install pulls the one dependency (google-auth-library).

Safety: search_gmail_for_job / read_gmail_message / scan_job_updates are read-only; draft_gmail_reply only ever creates a draft; send_gmail_email sends immediately and can't be undone, so it refuses without confirm: true and should only be called after you've reviewed the exact to/subject/body.

Safety & behavior notes

• Backups (rotating): every write first copies the file into a sibling .backups\ folder with a timestamped name (<file>.<YYYYMMDD-HHmmss-SSS>.bak), keeping the **last 10** per file. This replaces the old single-slot .bak, so repeated writes (manual edits or the daily task) can't clobber your last-good copy. Applies to the sheets, the prep file, and delete_document; promote_to_tracker backs up each file it writes. (Nothing is backed up when a file is created fresh.)

• Fresh reads: the workbook is re-read on every call, so edits you make directly in Excel are always reflected.

• Validation: row-editing tools verify the row exists (and is unambiguous) before changing anything; bad dates are rejected up front. promote_to_tracker refuses to create a duplicate tracker row.

• Dates (tracker only) are stored as Excel date serials formatted d-mmm-yy. New rows are written the same way, so 2026-06-01 shows as 1-Jun-26 — matching the existing rows. Reads/writes use timezone-free calendar-date math. Discovery dates are plain ISO text.

• Formatting preservation: new rows copy the number format (and, where the writer supports it, the cell style) of the last existing row, and column widths are preserved — the way a human copy-pasting a row would leave things.

  Note: the open-source SheetJS build faithfully preserves number formats and column widths (what this workbook uses). Rich per-cell styling (custom fonts/fills/borders) is not re-serialized by the community build; if you later add heavy cell styling, preserving it would require SheetJS Pro.

• File locked: if a file is open in another program (Excel for the sheets, Word/an editor for the prep .md), writes fail with a clear "please close it" message rather than a cryptic error.

Testing

npm test

test-client.mjs builds the server, then spins it up over stdio against self-contained fixtures in a temp folder and asserts on every tool (66 checks across the tracker, discovery, promote, interview-prep ambiguity, document, and backup paths). Your real files are never touched — the suite creates its own throwaway tracker/discovery/prep/Resumes in the OS temp dir and deletes them afterward. It exits non-zero if any check fails.

It does not send a physical print job — print_document is covered only via its error paths (missing file, unsupported type, unknown printer).