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 — no Python or other external interpreter required

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

• Data source: your .xlsx files, read/written with SheetJS (xlsx); styling (bold header, freeze/auto-filter, hyperlinks) via exceljs

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

• Resumes: .docx built in-process with the docx package; .pdf/.docx text extraction via pdf-parse + mammoth

• Board sweep: run_job_sweep probes ATS job boards directly over HTTP (native fetch), in-process — no external script

• Printing: silent PDF printing — pdf-to-printer (bundles SumatraPDF) on Windows, CUPS's lp on macOS/Linux; .docx is converted to PDF first using LibreOffice (any OS) or Microsoft Word (Windows only) if installed (optional — see Safety & behavior notes)

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

Prerequisites

Setting this up on a brand-new Windows 11 machine, with nothing installed yet? WINDOWS_SETUP.md is a complete beginner-friendly walkthrough — Node, the project files, Claude Desktop, and troubleshooting, in order. The steps below are the terse reference version.

• Node.js 18 or later — required. Download the LTS installer for your OS from nodejs.org and run it; verify with node --version.

• LibreOffice — optional. Only needed if you want generate_resume to also produce a .pdf (it always produces the .docx regardless). Works on Windows, macOS, and Linux. On Windows only, Microsoft Word (if already installed) works as an alternative — nothing extra to download for that path.

• Nothing else. No Python, no other interpreter, no compiler — every other dependency is pure JavaScript and installed by npm install below.

Related MCP server: career-agent

Build

cd mcp-job-tracker
npm install
npm run build

This produces dist/index.js. npm install pulls everything this server needs — pdf-to-printer (bundles SumatraPDF for silent Windows printing, no separate install; macOS/Linux print through CUPS's lp instead, no npm package needed), exceljs, docx, pdf-parse, mammoth — all pure JS, nothing to compile and no Python. The one optional external dependency is LibreOffice (any OS) or Microsoft Word (Windows only), used only to convert a generated resume's .docx to .pdf; if none is installed, generate_resume still produces the .docx and says so. The optional Gmail tools need a one-time npm run gmail:auth (see Gmail integration).

Configure Claude Desktop

Open Claude Desktop's config file:

Windows:  %APPDATA%\Claude\claude_desktop_config.json
macOS:    ~/Library/Application Support/Claude/claude_desktop_config.json

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

Windows:

{
  "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"
      }
    }
  }
}

macOS (same shape, forward-slash paths):

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

node above assumes it's on PATH; if Claude Desktop can't find it, replace "command": "node" with the absolute path from which node (macOS) / where node (Windows). setup.mjs (below) writes this file for you automatically, on either OS, so hand-editing it is only needed if you'd rather not use it.

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 — or, for a genuinely fresh start with no existing spreadsheet, skip this step and call the init_job_tracker_files tool once the server is running; it creates the folder and both blank, formatted workbooks for you.

3. Make sure Node.js 18+ is installed (node --version) — see Prerequisites above; nothing else is required for the server itself.

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

Setup

Discovery-sheet tools (Job_Search_Discovery.xlsx)

Search criteria & board sweep

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: SheetJS (used for the data read/write itself) doesn't re-serialize rich cell styling, so every MCP discovery write is followed by a best-effort exceljs reformat pass (xlsxFormat.ts) that (re)applies bold header / frozen row / auto-filter / wrapped text / clickable Job Link cells. Pure JS, nothing external required; if it ever fails for some reason the data write still succeeds (the tool returns formatted: false).

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 their own resume-generation script or moving bytes through base64, so it's the single resume path (resumeDocx.ts 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 resumeDocx.ts (the docx package, in-process; the measured spec: Liberation Serif, 20 pt name, ruled 11 pt headings, 0.63" margins, US Letter) → PDF via LibreOffice or Word, whichever is installed. ~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 — and only on Windows; macOS/Linux have no COM automation to fall back to, so LibreOffice is the sole path there (checked at /Applications/LibreOffice.app/... on macOS, common Linux install paths, then bare soffice on PATH).

• 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) on Windows, or CUPS's lp on macOS/Linux (present by default on macOS, and on any Linux with CUPS installed). No dialog, single copy, default settings either way.

• .docx is converted to a PDF next to it first — using LibreOffice (soffice --headless --convert-to pdf) if installed, otherwise (Windows only) Microsoft Word via COM. The PDF is cached and reused while it's newer than the docx. If no converter 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

npm test (via run-tests.mjs) runs two suites:

• test-client.mjs — an integration suite. Builds the server, spins it up over stdio against self-contained fixtures in a temp folder, and asserts on every tool (see the file for the current count — run npm test rather than trusting a hardcoded number here) across the tracker, discovery, promote, interview-prep ambiguity, document, search-criteria/sweep/ discovery-sync, setup, 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.

• test-unit.mjs — plain unit tests, importing dist/*.js directly (no server process) for the pure logic that lives right next to the network/ OAuth calls above: title/location classification, salary-text mining, per-ATS board-response parsing, Gmail header/MIME/raw-email helpers, and the board-health cache round-trip. This is exactly the logic that would otherwise go completely untested, since it sits inside the same files as the excluded network calls.

Either script exits non-zero if any check fails, and so does npm test.

It does not send a physical print job — print_document is covered only via its error paths (missing file, unsupported type, unknown printer). Likewise, run_job_sweep/runSweep() itself is only covered via its refuses-without- criteria path — it makes live outbound calls to ~95 real ATS endpoints, which isn't something either suite exercises automatically.

npm run coverage

Runs both suites together under c8 and prints a per-file statement/branch/function breakdown (plus an HTML report under coverage/, gitignored). sweepEngine.ts/gmailAuth.ts/gmailTools.ts wrap their genuinely network/OAuth-bound functions in /* c8 ignore */ comments — deliberately narrow: only the functions whose entire body is a live call are excluded, so pure logic living right next to them (and tested by test-unit.mjs) still counts. What's left uncovered after that is real, visible, and mostly runSweep()'s own orchestration plus the Gmail tool handlers' post-auth bodies — both need either mocking or real credentials/network to close further.