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

Related MCP server: Job Application MCP

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

Both are resolved against the process working directory when relative.

Enumerated values

Tools reference

Applications

Companies

Vacancies

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.