Skip to content
Back to search

Job-Tracker-MCP

Track your job search from Claude Code: MCP servers that scrape job postings into SQLite and manage Gmail, plus skills

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/nikhilmank--job-tracker-mcp/badge.svg)](/listings/nikhilmank--job-tracker-mcp)

HTML

<a href="/listings/nikhilmank--job-tracker-mcp"><img src="/api/listings/nikhilmank--job-tracker-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Requires Python 3.12+.

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
crawl4ai-setup            # installs the Playwright browser

Register the servers (this repo ships a project-scoped `.mcp.json`, so just start Claude Code in this folder). To register them elsewhere, use the venv interpreter directly:

claude mcp add jobtracker -s project -- .venv/bin/python main.py
claude mcp add gmail -s project -- .venv/bin/python gmail_mcp.py

`claude_desktop_config.example.json` shows the same for Claude Desktop (use absolute paths).

> **Do not use `uv run` to launch the servers and keep `fastmcp>=3.4.7,<4`.** Claude Code speaks MCP protocol `2024-11-05`; FastMCP 4.x does not, and the servers show "tools fetch failed / request timed out". Heavy libraries are imported lazily so the servers start in under a second; keep it that way.

Gmail (optional)

1. In Google Cloud Console create a project, enable the **Gmail API**, configure the OAuth consent screen (add your address as a test user) and create an **OAuth client ID** of type *Desktop app*. 2. Save the downloaded JSON as `gmail_credentials.json` in this folder. 3. Run `.venv/bin/python gmail_mcp.py --auth` and approve access. This writes `.gmail-token.json`.

Both files are git-ignored. Never commit them. Changing the scopes in `gmail_mcp.py` requires deleting the token and authenticating again. If something fails, see the `gmail-mcp-troubleshooting` skill.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 113 lines
  1. # JobTracker MCP
  2. Track your job search from Claude Code. Two local [MCP](https://modelcontextprotocol.io) servers plus a set of Claude Code skills:
  3. - **`jobtracker`** (`main.py`): scrapes job-posting URLs with [Crawl4AI](https://github.com/unclecode/crawl4ai) into a local SQLite database (`jobtracker.db`), or stores text you paste.
  4. - **`gmail`** (`gmail_mcp.py`): Gmail API wrapper (search, read, label, move, trash, send) used by the skills to file application receipts and rejections.
  5. - **Skills** (`.claude/skills/`): optional workflows that combine the two, e.g. a daily routine that adds today's applications, files confirmation emails and marks rejected jobs.
  6. Everything runs on your machine; your data stays in `jobtracker.db` and your own Gmail account.
  7. ## Tools
  8. | Server | Tools |
  9. |---|---|
  10. | jobtracker | `add_job`, `add_job_from_text`, `list_jobs`, `get_job`, `update_job`, `delete_job`, `search_jobs`, `get_stats` |
  11. | gmail | `search_emails`, `list_emails`, `get_email`, `send_email`, `update_labels`, `move_email`, `trash_email`, `get_gmail_stats` |
  12. Job statuses: `new`, `applied`, `interviewing`, `offer`, `rejected`, `archived`. `add_job` always stores `new`; set the real status with `update_job`.
  13. ## Setup
  14. Requires Python 3.12+.
  15. ```bash
  16. python -m venv .venv
  17. source .venv/bin/activate
  18. pip install -r requirements.txt
  19. crawl4ai-setup # installs the Playwright browser
  20. ```
  21. Register the servers (this repo ships a project-scoped `.mcp.json`, so just start Claude Code in this folder). To register them elsewhere, use the venv interpreter directly:
  22. ```bash
  23. claude mcp add jobtracker -s project -- .venv/bin/python main.py
  24. claude mcp add gmail -s project -- .venv/bin/python gmail_mcp.py
  25. ```
  26. `claude_desktop_config.example.json` shows the same for Claude Desktop (use absolute paths).
  27. > **Do not use `uv run` to launch the servers and keep `fastmcp>=3.4.7,<4`.** Claude Code speaks MCP protocol `2024-11-05`; FastMCP 4.x does not, and the servers show "tools fetch failed / request timed out". Heavy libraries are imported lazily so the servers start in under a second; keep it that way.
  28. ### Gmail (optional)
  29. 1. In Google Cloud Console create a project, enable the **Gmail API**, configure the OAuth consent screen (add your address as a test user) and create an **OAuth client ID** of type *Desktop app*.
  30. 2. Save the downloaded JSON as `gmail_credentials.json` in this folder.
  31. 3. Run `.venv/bin/python gmail_mcp.py --auth` and approve access. This writes `.gmail-token.json`.
  32. Both files are git-ignored. Never commit them. Changing the scopes in `gmail_mcp.py` requires deleting the token and authenticating again. If something fails, see the `gmail-mcp-troubleshooting` skill.
  33. ## Usage
  34. Ask Claude in plain language, or call the tools directly:
  35. ```text
  36. add_job("https://jobs.example.com/senior-engineer")
  37. update_job(job_id, status="applied")
  38. list_jobs(status="applied")
  39. search_jobs("python remote")
  40. ```
  41. - LinkedIn and StepStone block scraping via robots.txt and the check is deliberately kept on. Paste the description with `add_job_from_text` instead.
  42. - If a scrape stores blank fields or a thin description, fix it with `update_job`. `add_job` returns warnings describing the problem.
  43. - Extraction understands German-language postings and DACH conventions (Standort, `(m/w/d)`, GmbH/AG, `3.500,00 €`) as well as English ones.
  44. - Back up before bulk changes: `.venv/bin/python scripts/backup_db.py` (one dated copy per day in `backups/`, 30 days kept).
  45. ### Daily workflow
  46. Paste the jobs you applied to into `data/todays_jobs.md` (links, or pasted descriptions for Easy Apply jobs) and tell Claude *"update the db with today's jobs"*. The `daily-job-routine` skill adds them, files the confirmation emails and handles rejections.
  47. ## Gmail skills and labels
  48. The skills file mail into labels under one parent label, **`JobApplications`** by default:
  49. | Label | Meaning |
  50. |---|---|
  51. | `JobApplications` | application confirmations |
  52. | `JobApplications/EasyApply` | LinkedIn Easy Apply receipts |
  53. | `JobApplications/Rejected` | rejections |
  54. | `JobApplications/Shortlisted` | positive replies (stay in the inbox, starred) |
  55. | `JobApplications/NeedsAttention` | mail that asks you to do something |
  56. Create these labels in Gmail first. To use another prefix set `JOBTRACKER_LABEL_PREFIX` (for example `export JOBTRACKER_LABEL_PREFIX=Jobs2026`) before running Claude Code. Set `JOBTRACKER_USER_HINTS="yourname,yourdomain.com"` (comma separated) so the classifiers can recognise mail you sent yourself.
  57. | Skill | Purpose |
  58. |---|---|
  59. | `daily-job-routine` | one-shot: add today's jobs, file receipts and rejections, delete job alerts, report what needs you |
  60. | `gmail-job-inbox-triage` | classify the inbox (needs-you, rejection, confirmation, alert) and file the clear cases |
  61. | `gmail-file-applications` | file application confirmations |
  62. | `gmail-file-rejections` | sentence-level rejection classifier and filer |
  63. | `jobtracker-gmail-sync` | update job statuses from Gmail evidence |
  64. | `jobtracker-csv-import` | bulk-import a spreadsheet export |
  65. | `gmail-mcp-troubleshooting` | fix startup, OAuth and quota problems |
  66. Scripts that change anything (database, Gmail labels) default to a dry run and need `--apply`. The classifiers favour precision: when unsure, a mail stays in the inbox. Their sender and phrase lists are tuned for English and German mail. Edit the rules in `.claude/skills/gmail-job-inbox-triage/scripts/triage_rules.py` for your own market.
  67. ## Tests
  68. Plain scripts, no pytest; each exits 1 on failure:
  69. ```bash
  70. .venv/bin/python scripts/test_job_extract.py
  71. .venv/bin/python .claude/skills/gmail-file-rejections/scripts/test_classifier.py
  72. .venv/bin/python .claude/skills/gmail-file-applications/scripts/test_confirmation.py
  73. .venv/bin/python .claude/skills/gmail-job-inbox-triage/scripts/test_triage.py
  74. ```
  75. ## Privacy
  76. `jobtracker.db`, `backups/`, `data/` (except the empty template), the Gmail token and credentials are git-ignored. Check `git status` before every commit.
  77. ## License
  78. MIT, see `LICENSE`.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.