# Jobtrack

> A flight recorder for job applications — plain-file snapshots, queryable via CLI or AI (MCP).

- **Type:** MCP server
- **Install:** `agentstack add mcp-james5101-jobtrack`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [james5101](https://agentstack.voostack.com/s/james5101)
- **Installs:** 0
- **Category:** [Search](https://agentstack.voostack.com/c/search)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [james5101](https://github.com/james5101)
- **Source:** https://github.com/james5101/jobtrack

## Install

```sh
agentstack add mcp-james5101-jobtrack
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# jobtrack

[](https://github.com/james5101/jobtrack/actions/workflows/test.yml)

Local-first CLI + MCP server for tracking job applications. A flight recorder, not a filing cabinet.

## Install (dev)

```bash
uv sync
uv pip install -e ".[dev]"
```

## Quickstart

```bash
# Paste-driven (most reliable for modern job boards)
jobtrack add --company Valon --role "Platform Engineer" \
    --resume ~/resumes/platform.pdf --jd-paste

# Or attach a saved JD file, with a cover letter and tags
jobtrack add --company Stripe --role SRE \
    --resume ~/resumes/sre.pdf --jd-file ~/jds/stripe-sre.md \
    --cover ~/covers/stripe.md --tag payments --tag fintech

jobtrack list
jobtrack list --status interviewing
jobtrack show valon                 # by company
jobtrack show 2026-05-10_valon_...  # by full ID
jobtrack open valon                 # opens snapshot dir in OS file browser

jobtrack status  screening
jobtrack note  "recruiter asked about k8s depth"
jobtrack tag  +fintech -ghosted
```

## Status pipeline

Seven values, one enum, no enforced transitions:

```
applied → screening → interviewing → offer
                                   ↘ rejected
                                   ↘ ghosted
                                   ↘ withdrawn
```

`applied` is set automatically. The rest are moved with `jobtrack status` (CLI) or `update_status` (MCP). Every change appends to `status_history` — nothing is overwritten.

## Snapshot layout

Each application is a directory under `/applications/`:

```
2026-05-10_valon_platform-engineer_a3f1/
├── meta.json
├── resume.pdf            # exact bytes sent, with sha256 in meta.json
├── resume.txt            # extracted on add — the search sidecar
├── job-description.md
└── cover-letter.md       # if provided
```

ID format: `YYYY-MM-DD___`. The 4-hex suffix is `sha256(applied_at)[:4]` so IDs stay unique even if you apply to the same role twice in a day.

## Where data lives

- Windows: `%LOCALAPPDATA%\jobtrack`
- macOS: `~/Library/Application Support/jobtrack`
- Linux: `~/.local/share/jobtrack`

Override with `JOBTRACK_HOME=/path/to/dir`.

## Demo

Build a throwaway store with five sample applications run through every status:

```bash
bash scripts/demo-pipeline.sh /tmp/jobtrack-demo
JOBTRACK_HOME=/tmp/jobtrack-demo jobtrack list
```

Useful for verifying an install or showing someone what the tool does without polluting your real data store.

## Tests

```bash
uv run pytest
```

## MCP server

`jobtrack-mcp` is a FastMCP server exposing five read tools and three write tools:

**Read:**
- `list_applications(status?, tag?, since?, limit?)` — summaries
- `get_application(query)` — full meta + resume text + JD + cover letter
- `find_application_by_company(company)` — all summaries matching a company name (substring)
- `search_applications(query)` — substring search across all snapshot files and notes
- `get_recent(n=5)` — the N most recent with full content

**Write:**
- `update_status(query, status)` — append-only status change
- `add_note(query, note)` — append a note
- `edit_tags(query, add?, remove?)` — tag arithmetic

Writes require an exact ID or a uniquely-resolving company name; ambiguous queries return candidate IDs instead of silently writing to the wrong record. Creating new applications stays CLI-only (you have files on disk when you apply).

### Claude Desktop

Edit `%APPDATA%\Claude\claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "jobtrack": {
      "command": "D:\\code\\application-tracker\\.venv\\Scripts\\jobtrack-mcp.exe"
    }
  }
}
```

If you keep your data outside the default location, add an `env` block — otherwise the MCP server reads the wrong store and will report no results:

```json
{
  "mcpServers": {
    "jobtrack": {
      "command": "D:\\code\\application-tracker\\.venv\\Scripts\\jobtrack-mcp.exe",
      "env": {
        "JOBTRACK_HOME": "D:\\jobtrack-data"
      }
    }
  }
}
```

Restart Claude Desktop. Try: *"What did I send to Valon?"*

### Claude Code

```powershell
claude mcp add jobtrack -- uv --directory D:\code\application-tracker run jobtrack-mcp
```

To pass `JOBTRACK_HOME`, use `--env`:

```powershell
claude mcp add jobtrack --env JOBTRACK_HOME=D:\jobtrack-data -- `
    uv --directory D:\code\application-tracker run jobtrack-mcp
```

Or edit `.mcp.json` in the project directly:

```json
{
  "mcpServers": {
    "jobtrack": {
      "command": "uv",
      "args": ["--directory", "D:\\code\\application-tracker", "run", "jobtrack-mcp"],
      "env": {
        "JOBTRACK_HOME": "D:\\jobtrack-data"
      }
    }
  }
}
```

The MCP server resolves `JOBTRACK_HOME` exactly like the CLI: env var if set, otherwise the platform default from "Where data lives" above. The two **must** agree, or the CLI and MCP will see different stores.

## Skills (Claude Code)

The repo ships Claude Code skills under `.claude/skills/`. They load automatically when you run Claude Code in this directory.

**Development skills** — keep extensions consistent with the project's patterns:

- `add-mcp-tool` — add a read/write tool to the FastMCP server
- `add-cli-command` — add a `jobtrack ` subcommand
- `add-application-field` — add a field to the `ApplicationMeta` schema (covers backwards-compat with existing snapshots)

**Workflow skills:**

- `smart-job-search` — find new openings across employers' career boards, dedupe against what's already tracked (via the MCP read tools), rank by résumé fit, and write per-company files plus a ranked shortlist to a (gitignored) `jobs/` folder. The intelligence runs in your Claude session; jobtrack supplies the data. Reading JS career boards uses a browser tool — **Claude in Chrome** for logged-in/interactive sources (e.g. LinkedIn), or **headless Playwright** for public boards and unattended runs. A `PreToolUse` hook in `.claude/settings.json` keeps a run bounded (no exhaustive crawling, API reverse-engineering, or scratch dumps in the repo); review or disable it via `/hooks`.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [james5101](https://github.com/james5101)
- **Source:** [james5101/jobtrack](https://github.com/james5101/jobtrack)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-james5101-jobtrack
- Seller: https://agentstack.voostack.com/s/james5101
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.