j-hunt-mcp

j-hunt-mcp

A local job-hunting MCP server built on the official Python SDK (mcp / FastMCP). It runs over stdio for Claude Desktop / Claude Code and helps with the full loop:

• Discover jobs across pluggable web sources — including geo / map-region search.
• Track applications through a status lifecycle.
• Store a profile & resume the assistant can reference.
• Tailor resumes / cover letters via reusable prompts (the client LLM does the writing).

Architecture

Strict, one-directional layering keeps business logic out of the MCP glue:

tools/ • resources.py • prompts.py   (thin MCP adapters — no logic)
            │
            ▼
        services/         (all business logic; constructor-injected deps)
            │
   ┌────────┼─────────────┐
   ▼        ▼             ▼
repositories/  scraping/   geo.py        (SQLite • job sources • Google Maps)
   │
   ▼
models/   (pure Pydantic domain types, reused by every layer)

| Layer | Location | Responsibility | |-------|----------|----------------| | Models | src/jhunt_mcp/models/ | Pure Pydantic domain types (one file per domain) | | Repositories | src/jhunt_mcp/repositories/ | SQLite persistence; map rows ↔ models (SQLAlchemy tables kept separate) | | Services | src/jhunt_mcp/services/ | Business logic (search, tracking, profile, geo) | | Scraping | src/jhunt_mcp/scraping/ | Pluggable JobSource registry + sources | | Tools/Resources/Prompts | src/jhunt_mcp/tools/, resources.py, prompts.py | Thin MCP adapters over services |

Setup

Requires Python ≥ 3.10 and uv.

uv sync                      # install deps
cp .env.example .env         # optional: add GOOGLE_MAPS_API_KEY for geo search
uv run pytest                # run the test suite (offline)

Run / develop

uv run j-hunt-mcp                          # run the stdio server directly
uv run mcp dev src/jhunt_mcp/server.py     # open the MCP Inspector (needs Node/npx)

Register with Claude Desktop

uv run mcp install src/jhunt_mcp/server.py --name "Job Hunt" \
    -v GOOGLE_MAPS_API_KEY=your_key_here

Restart Claude Desktop; the Job Hunt server's tools then appear.

Capabilities

Tools

| Tool | Purpose | |------|---------| | search_jobs | Keyword search; optional location + radius_km for nearby jobs | | search_jobs_in_region | Search inside a map-selected bounding box (NE/SW corners) | | geocode_location | Resolve a place name → coordinates + formatted address | | save_job / list_saved_jobs | Persist and list jobs | | log_application | Record an application (by saved job_id or ad-hoc url) | | update_application_status | Move an application through its lifecycle (validated) | | set_next_action | Set a follow-up reminder on an application | | list_applications | List applications, optionally filtered by status | | get_profile / update_profile / set_resume | Manage the stored profile & resume |

Resources: profile://me, resume://current, jobs://saved, applications://{status} (use all).

Prompts: tailor_resume, draft_cover_letter, application_followup_email.

Geo / map-region search

There is no map UI in the server itself — a client passes the result of a map selection as parameters. Three shapes are supported, all requiring GOOGLE_MAPS_API_KEY:

• a place string + radius_km (search_jobs),
• a bounding box (search_jobs_in_region) — what a map rectangle yields,
• (internally) a center + radius.

Geocoding results are cached in SQLite to conserve API quota. Without a key, plain keyword search still works; geo paths return a clear error.

Job sources & scraping note

Major boards (LinkedIn, Indeed) actively block scraping and forbid it in their ToS. v1 therefore ships sources that expose public JSON/RSS and are scraping-tolerant: RemoteOK, WeWorkRemotely, Hacker News "Who is hiring?". Requests are rate-limited per host. Add a board by implementing scraping/base.py:JobSource.

Secrets

Never commit credentials. The only secret today is GOOGLE_MAPS_API_KEY, read from a gitignored .env via pydantic-settings. When authenticated boards are added later, use the OS keyring for passwords and the SQLite DB for session cookies — never JSON in the repo. mcp install ... -v KEY=value injects env vars without writing them to source.

Data

The SQLite database lives at data/jhunt.db by default (override with JHUNT_DB_PATH). The data/ directory is gitignored.