Job Tracker MCP

Job Tracker MCP

A local-first MCP server for tracking applications, contacts, interviews, follow-ups, and career workflows from Claude or any compatible MCP client.

Why it exists

Job searches create many small, high-context tasks: remembering status changes, following up at the right time, preparing for interviews, and keeping contact history connected to applications. Job Tracker MCP turns those tasks into validated tools backed by local SQLite storage, with a REST API and dashboard when a visual workflow is useful.

Features

Quick start

npm ci
npm run build
npm run dev

The last command starts the stdio MCP server. To run the REST API instead:

npm run dev:api

To inspect the MCP server interactively:

npm run inspect

Node.js 22 or newer is recommended. Runtime data is created under data/ and is ignored by Git.

Use with MCP clients

Build first so the client runs the compiled package. Replace /absolute/path/to/repo with the clone location.

Claude Desktop, macOS and Linux

Typical config file: ~/Library/Application Support/Claude/claude_desktop_config.json on macOS, or ~/.config/Claude/claude_desktop_config.json on Linux.

{
  "mcpServers": {
    "job-tracker": {
      "command": "node",
      "args": ["/absolute/path/to/repo/dist/index.js"],
      "cwd": "/absolute/path/to/repo"
    }
  }
}

Claude Desktop, Windows

Use forward slashes in JSON paths:

{
  "mcpServers": {
    "job-tracker": {
      "command": "C:/Program Files/nodejs/node.exe",
      "args": ["C:/Users/YOUR_USERNAME/path/to/repo/dist/index.js"],
      "cwd": "C:/Users/YOUR_USERNAME/path/to/repo"
    }
  }
}

Cursor or VS Code

Register the same command in the client's MCP settings. The command is node, the argument is the absolute path to dist/index.js, and the working directory is the repository root. Restart the client after changing its configuration.

Configuration

tracker.config.json defines the default jobs tracker and alternate scholarships, university, and visas workflows. Set TRACKER_CONFIG_PATH to load another file and TRACKER_TYPE to select a tracker.

Important environment variables:

Dashboard

Live demo: https://jht127.github.io/job-tracker-mcp/

cd job-tracker-dashboard/job-tracker-dashboard
npm ci
npm run dev

For a production build, run npm run build. The dashboard uses the API first and falls back to demo data when VITE_DEMO=true or the API is unavailable.

Documentation

• Architecture
• REST API
• Generated MCP tool reference
• Live demo walkthrough
• Threat model
• Security policy
• Contributing
• Roadmap
• Changelog

Tool reference maintenance

The tool reference is generated from the live built MCP server and its actual schemas:

npm run build
npm run generate:tools
npm run check:tools

CI fails when docs/tool-reference.md is stale.

Architecture

flowchart LR
  Client[MCP client] --> Transport[stdio or Streamable HTTP]
  Browser[Dashboard] --> REST[REST API]
  Transport --> Tools[MCP tools]
  Tools --> Core[Shared core services]
  REST --> Core
  Core --> Storage[(SQLite or JSON)]
  Core --> Integrations[Optional integrations]

Live demo

The hosted dashboard runs in VITE_DEMO=true mode with fictional in-memory data, so visitors can try the board, timeline, contacts, search, theme, language, and Connect Claude views without backend credentials. See docs/demo-script.md for the walkthrough.

Development

npm ci
npm run typecheck
npm run lint
npm test
npm run build

For package and container checks:

npm pack
docker build -t job-tracker-mcp:local .

The project uses Conventional Commits. See CONTRIBUTING.md before opening a pull request.

License

ISC. See LICENSE.