job-tracker-mcp

A local-first MCP server for tracking job applications, companies, and vacancies from Claude — or any other MCP client. Everything lives in a single SQLite file on your machine; nothing is sent anywhere.

The point is to stop keeping a job search in a spreadsheet. You are already talking to an assistant while tailoring a resume or reading a job description, so the assistant may as well be the one writing the record: "add an application for Acme, senior frontend, applied today", "what should I follow up on", "show me the funnel".

Features

• 19 MCP tools over three linked entities: companies → vacancies → applications
• Company database — employers with sphere, offices, work format, relocation policy, relevance, priority, and research status (new → researching → target → applied / not_interested / blacklist)
• Vacancies — open roles filed under a company, with track, seniority, salary range, and full JD text
• Applications — status pipeline (draft, applied, screening, tech_interview, final, offer, rejected, ghosted), contact details, notes, and per-application timeline events
• Follow-up queue — overdue actions, applications gone quiet for 5+ days, and what is due this week
• Funnel analytics — stage-by-stage conversion plus a breakdown by resume variant, so you can see which version of your resume actually converts
• File attachments — resumes, cover letters, and JDs copied into a managed data directory and linked to the application
• Auto-migrations — the schema is created and upgraded on startup; there is no separate setup step

Architecture

MCP client (Claude, etc.)
        │  stdio, newline-delimited JSON-RPC
        ▼
   src/mcp.ts          tool registration, zod input schemas, error mapping
        ▼
   src/core/*          applications, companies, vacancies, stats, dashboard, attachments
        ▼
   better-sqlite3      single file, WAL mode, foreign keys on
        ▲
   migrations/*.sql    applied in filename order, tracked in a migrations table

The core/ layer holds all the business logic and knows nothing about MCP. That was deliberate: this code originally sat behind both a REST API and an MCP server in the same project, and the two interfaces were thin adapters over the same functions. Only the MCP adapter was carried over here, but the seam is still there — core/ throws ApiError with an HTTP-ish status code, and mcp.ts translates that into an MCP error result.

Writes are synchronous (better-sqlite3 is a blocking driver), which is exactly what you want for a single-user local tool: no connection pool, no async bookkeeping, and multi-statement changes run inside real transactions.

Quick start

Requires Node.js 20.11+.

git clone https://github.com/kurkul608/job-tracker-mcp.git
cd job-tracker-mcp
npm install
npm run build

Register it with Claude Code:

claude mcp add job-tracker -- node /absolute/path/to/job-tracker-mcp/dist/mcp.js

Or add it to .mcp.json by hand:

{
  "mcpServers": {
    "job-tracker": {
      "command": "node",
      "args": ["/absolute/path/to/job-tracker-mcp/dist/mcp.js"],
      "env": {
        "JOB_TRACKER_DB_PATH": "/absolute/path/to/your/job-tracker.db"
      }
    }
  }
}

Set JOB_TRACKER_DB_PATH explicitly if you use it from an MCP client — clients start the server with their own working directory, and the default path is relative to it.

For local development without a build step:

npm run dev

Configuration

Environment variables

Variable	Default	Purpose
JOB_TRACKER_DB_PATH	./data/job-tracker.db	SQLite database file. Parent directory is created if missing.
JOB_TRACKER_FILES_DIR	./data/files	Root for attachments. Each application gets a <id>-<company-slug>/ subdirectory.

Both are resolved against the process working directory when relative.

Enumerated values

Field	Values
Application status	draft, applied, screening, tech_interview, final, offer, rejected, ghosted
resume_variant	frontend, fullstack, ai
Company status	new, researching, target, applied, not_interested, blacklist
Vacancy status	open, applied, closed, irrelevant
Vacancy track	frontend, fullstack, backend, ai, other
relevance	high, medium, low
relocation	yes, no, unknown
priority	1–3

Tools reference

Applications

Tool	Description	Key parameters
add_application	Create an application record. A bare company name auto-creates the company; pass vacancy_id or company_id to file it under existing records.	company, company_id, vacancy_id, position, jd_url, jd_text, source, salary_range, location_policy, notes, resume_variant, status, contact_name, contact_channel, contact_value, next_action_at
get_application	Full application detail including timeline events and attachments.	id
list_applications	List applications, optionally filtered.	status, source, q, company_id, vacancy_id
update_application	Update editable fields; only provided fields change.	id + any add_application field
update_status	Move an application to another pipeline stage.	id, status
add_note	Append a note, call, or email to the application timeline.	id, text, type (note|call|email)
attach_resume	Copy a file into the tracker's data directory and link it. kind=resume also sets the application's resume_path.	id, file_path, kind (resume|cover_letter|jd|other)
list_pending	Follow-up queue: overdue actions, applications with no answer for 5+ days, and the upcoming week.	—
funnel_stats	Funnel counts with stage-to-stage conversion, plus a breakdown by resume variant.	—

Companies

Tool	Description	Key parameters
list_companies	List employers with filters for text, status, relevance, sphere, priority, remote/US-only, relocation, and whether they have open vacancies.	q, status, relevance, sphere, priority, remote_only, us_only, relocation, has_vacancies, limit
get_company	One company with its full tree: vacancies, and the applications filed under each.	id
add_company	Add an employer. Fails if the name already exists.	name, sphere, offices, market, work_format, careers_url, linkedin_url, website, relocation, is_remote, has_us, relevance, status, priority, notes, source
upsert_company	Create, or update the existing company matched by name. Useful when writing back research results.	same as add_company
update_company	Update an employer by id; only provided fields change.	id + any add_company field
company_overview	Counts across the company database plus the list of distinct spheres.	—

Vacancies

Tool	Description	Key parameters
add_vacancy	Add an open role under a company.	company_id, title, track, seniority, url, location, work_format, salary_range, jd_text, status, priority, notes, posted_at
list_vacancies	List vacancies across companies.	company_id, status, track, priority, q, limit
get_vacancy	One vacancy with its company and the applications filed against it.	id
update_vacancy	Update a vacancy; only provided fields change.	id + any add_vacancy field

Example prompts

Once the server is registered, these work as plain requests:

• "Add an application for Acme Corp, Senior Frontend Engineer, found on LinkedIn, remote US, I used the fullstack resume."
• "I just had a screening call with Acme — move it to screening and log a note about what they asked."
• "What do I need to follow up on today?"
• "Show my funnel stats — which resume variant converts best?"
• "Add Globex to the company database: fintech, remote-first, has a US office, mark it high relevance and priority 1."
• "List target companies with open frontend vacancies that I haven't applied to yet."
• "Add the vacancy from this URL under Globex, then create an application against it."
• "Attach ~/resumes/acme-frontend.pdf to application 12 as the resume."

Data and privacy

Everything is local. The database is a single SQLite file, attachments are plain files on disk, and the server speaks only stdio to its client. The default data/ directory is gitignored.

Development

npm run dev     # run from source with tsx
npm run build   # compile to dist/
npm start       # run the compiled server

The schema lives in migrations/. To change it, add a new numbered .sql file — it is applied on the next startup and recorded in the migrations table. Existing files are never re-run.

License

MIT — see LICENSE.