# jobhunt_mcp

A personal MCP server that turns Claude into your job-search operations manager:

- **Search** live postings across LinkedIn, Indeed, ZipRecruiter, Glassdoor (JSearch API) plus Adzuna
- **Track** every application in a Google Sheet (status, priority, notes)
- **Follow up** on schedule — overdue nudges surface automatically
- **Network** — keep contacts per company and pull them into prep
- **Tailor** — one tool assembles the job description + your master resume + contacts so Claude can write a targeted resume and cover letter, saved straight to Google Drive

By design it **never auto-submits applications**. Auto-submission bots violate job-board terms of service and get flagged. The `prepare_application_package` tool gets you to "review and click submit" in one step instead.

## Prerequisites

- **Python 3.10+**
- An **MCP client** — [Claude Desktop](https://claude.ai/download) is assumed below, but any MCP-compatible client works.
- A **Google account** (for the Sheets tracker + Drive resume storage).
- *(Optional)* free **RapidAPI** and/or **Adzuna** accounts for live job search.

## Setup

Setup is: create a Google service account, share a Sheet + Drive folder + resume with it, (optionally) grab search-API keys, then point Claude Desktop at `server.py`. Budget ~10 minutes for the Google steps.

### 1. Google service account (~5 minutes)

1. Go to <https://console.cloud.google.com> → create a project (e.g. `jobhunt`).
2. Enable the **Google Sheets API** and **Google Drive API** (APIs & Services → Library).
3. APIs & Services → Credentials → **Create credentials → Service account**. Any name is fine; skip optional steps.
4. Open the service account → **Keys → Add key → JSON**. Save the file somewhere safe, e.g. `~/.config/jobhunt/service-account.json`.
5. Copy the service account's **email address** (ends in `.iam.gserviceaccount.com`) — you'll share things with it next.

### 2. Google Sheet (the tracker database)

1. Create a blank Google Sheet named e.g. "Job Hunt Tracker".
2. Share it with the service account email as **Editor**.
3. Grab the spreadsheet ID from the URL: `docs.google.com/spreadsheets/d/`**`<THIS_PART>`**`/edit`.

The server creates the `Jobs`, `Contacts`, and `Activity` tabs with headers automatically on first use.

### 3. Google Drive folder + master resume

1. Create a Drive folder e.g. "Job Applications"; share with the service account as **Editor**. Copy its folder ID from the URL.
2. Put your master resume in Drive as a **Google Doc** (the everything-you've-ever-done version — tailoring trims it down). Share it with the service account. Copy its file ID.

### 4. Search API keys (optional)

**JSearch (recommended — searches all boards at once):** free at <https://rapidapi.com> → search "JSearch" → subscribe to the Basic (free) plan → copy your RapidAPI key into `RAPIDAPI_KEY`.

**Adzuna:** free at <https://developer.adzuna.com> → register → copy your App ID and App Key into `ADZUNA_APP_ID` and `ADZUNA_APP_KEY`.

Skip these if you'd rather paste postings in manually with `jobhunt_add_job`.

### 5. Install and configure

```bash
pip install -r requirements.txt
```

Copy `claude_desktop_config.example.json` into your Claude Desktop config (`claude_desktop_config.json`), then fill in the `args` path to `server.py`, the `GOOGLE_SERVICE_ACCOUNT_FILE` path, and the IDs/keys from the steps above.

Config file locations:
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json` (use `"python"` for `command` and double-backslash paths, e.g. `C:\\Users\\you\\jobhunt-mcp\\server.py`)
- **Linux:** `~/.config/Claude/claude_desktop_config.json`

Restart Claude Desktop (fully quit — on Windows/macOS check the tray/menu bar). The `jobhunt` tools appear once the server starts.

#### Environment variables

Everything is configured through the `env` block of the Claude Desktop config:

| Variable | Required | Description |
|---|---|---|
| `GOOGLE_SERVICE_ACCOUNT_FILE` | ✅ | Absolute path to your service account JSON key |
| `JOBHUNT_SPREADSHEET_ID` | ✅ | ID of the tracker Google Sheet (shared with the service account) |
| `JOBHUNT_DRIVE_FOLDER_ID` | ✅ | ID of the Drive folder for saved documents |
| `JOBHUNT_MASTER_RESUME_FILE_ID` | ✅ | ID of your master resume Google Doc |
| `RAPIDAPI_KEY` | optional | RapidAPI key for JSearch (`jobhunt_search_all_boards`) |
| `ADZUNA_APP_ID` | optional | Adzuna App ID for `jobhunt_search_jobs` |
| `ADZUNA_APP_KEY` | optional | Adzuna App Key for `jobhunt_search_jobs` |
| `ADZUNA_COUNTRY` | optional | Adzuna country code (default `us`) |

### 6. Verify it works

Test the server standalone with the MCP Inspector any time (no Claude Desktop needed):

```bash
npx @modelcontextprotocol/inspector python3 server.py
```

Then try `jobhunt_get_master_resume` (confirms Drive access) and `jobhunt_list_jobs` (confirms Sheets access). If both return without an auth error, you're set.

## Tools

| Tool | What it does |
|---|---|
| `jobhunt_search_all_boards` | Aggregated search across LinkedIn/Indeed/ZipRecruiter/Glassdoor via JSearch (RapidAPI) |
| `jobhunt_search_jobs` | Search live postings (Adzuna) |
| `jobhunt_add_job` | Save a posting to the tracker (paste the full description!) |
| `jobhunt_list_jobs` / `jobhunt_get_job` | Browse the pipeline / full record |
| `jobhunt_update_job_status` | Move through discovered → preparing → applied → interviewing → offer |
| `jobhunt_log_activity` | Log interviews, emails, notes; schedule follow-ups (`+7` = 7 days) |
| `jobhunt_get_followups_due` | Surface overdue and upcoming follow-ups |
| `jobhunt_add_contact` / `jobhunt_list_contacts` | Networking CRM per company |
| `jobhunt_get_master_resume` | Pull your master resume from Drive |
| `jobhunt_save_document` | Save tailored resumes/cover letters to Drive as Google Docs |
| `jobhunt_prepare_application_package` | Everything needed to tailor and apply, in one call |

## Example prompts to try

- "Search all boards for SOC detection engineer roles near Dallas posted this week, and save the three best fits."
- "Prepare an application package for job a1b2c3d4, tailor my resume to it, and save both docs."
- "What follow-ups am I behind on?"
- "I just finished the phone screen with Acme — log it and remind me to send a thank-you note tomorrow."

## Security notes

- The service account JSON key is a credential — keep it out of git and shared folders.
- The service account can only touch files you explicitly shared with it.
- Treat job descriptions fetched from the web as untrusted content; the server stores them as plain data.