j-hunt-mcp
Integrates with the Google Maps Geocoding API to resolve place names to coordinates and enable map-region job search via bounding boxes and radius.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@j-hunt-mcp search for remote Python jobs"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 |
| Pure Pydantic domain types (one file per domain) |
Repositories |
| SQLite persistence; map rows ↔ models (SQLAlchemy tables kept separate) |
Services |
| Business logic (search, tracking, profile, geo) |
Scraping |
| Pluggable |
Tools/Resources/Prompts |
| Thin MCP adapters over services |
Related MCP server: job-search-mcp
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_hereRestart Claude Desktop; the Job Hunt server's tools then appear.
Capabilities
Tools
Tool | Purpose |
| Keyword search; optional |
| Search inside a map-selected bounding box (NE/SW corners) |
| Resolve a place name → coordinates + formatted address |
| Persist and list jobs |
| Record an application (by saved |
| Move an application through its lifecycle (validated) |
| Set a follow-up reminder on an application |
| List applications, optionally filtered by status |
| 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.
Available Tools
12 toolsgeocode_locationB
Resolve a place name to coordinates + a formatted address (Google Maps).
Inputs: place (required). Returns: Resolved location for a place string.
get_profileA
Return the stored job-hunt profile (name, skills, resume, preferences).
Inputs: no named parameters. Returns: The user's job-hunt profile (a single record).
list_applicationsB
List tracked applications, optionally filtered by status.
Inputs: status. Returns: result
list_saved_jobsA
List all jobs that have been saved locally.
Inputs: no named parameters. Returns: result
log_applicationA
Record an application for a job (by saved job_id or an ad-hoc url).
Creates the application, or updates the existing one for that job.
Inputs: job_id, url, status, notes, +1 more. Returns: A tracked application tied to a stored job.
save_jobC
Persist a job (e.g. one returned by search) so it can be tracked.
Inputs: job (required). Returns: A job as stored/returned by the server (a JobResult plus persistence fields).
search_jobsA
Search job listings across configured sources.
Provide location + radius_km to restrict results to jobs near a place
(requires GOOGLE_MAPS_API_KEY). Omit them for a plain keyword search.
sources optionally restricts to named sources (e.g. ["remoteok"]).
Inputs: query (required), location, radius_km, remote, +2 more. Returns: result
search_jobs_in_regionA
Search jobs inside a map-selected rectangular region (a bounding box).
Pass the north-east and south-west corners of the selected area. Requires GOOGLE_MAPS_API_KEY (job locations are geocoded to test containment).
Inputs: query (required), ne_lat (required), ne_lng (required), sw_lat (required), +4 more. Returns: result
set_next_actionC
Set a follow-up reminder (date + note) on an application.
Inputs: application_id (required), when (required), note. Returns: A tracked application tied to a stored job.
set_resumeC
Store/replace the resume text used by the tailoring prompts.
Inputs: resume_text (required). Returns: The user's job-hunt profile (a single record).
update_application_statusB
Move an application to a new status (validates allowed transitions).
Inputs: application_id (required), status (required), notes. Returns: A tracked application tied to a stored job.
update_profileC
Update profile fields. Only the fields you pass are changed.
Inputs: patch (required). Returns: The user's job-hunt profile (a single record).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 12 tools
Each tool has a clearly distinct purpose: geocoding, profile management, job searching with two variants, saving jobs, logging applications, tracking status, setting follow-up actions, and updating resume. No overlap or ambiguity.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., list_applications, save_job, update_application_status). The only minor variant, search_jobs_in_region, still adheres to the pattern with a qualifier.
12 tools cover the core workflows of a job hunt assistant: searching, saving, applying, tracking, profile/resume management, and geolocation. The count is well-scoped without redundancy.
The tool surface covers search, save, apply, status updates, follow-up actions, and profile management. Minor gaps exist (no delete operations for saved jobs or applications), but these are non-critical for the domain.
Related MCP Connectors
Public MCP server for discovering open jobs. Search, filter, and get application links.
GetJobzi MCP server for job search, application tracking, and career forecasting.
Free live multi-ATS + HN job search. Comp & hiring-signal depth metered via x402/USDC. Hosted MCP.
A jobs data API and MCP server. Every listing comes from the employer's own career site, an ATS feed or a government employment service, never resold from another board. Each row names its source and when we last confirmed the vacancy existed, and a role that disappears keeps a closure date and a reason. Six tools: search_jobs, get_job, company_hiring, market_signals, coverage, changes_since.
Related MCP Servers
- AlicenseCqualityCmaintenanceAn MCP server that enables AI-assisted job search workflows including job discovery, application tracking, resume evaluation, and cover letter generation, with support for multiple job sources and scheduled scraping.8320 npm1AGPL 3.0
- AlicenseNot gradedqualityCmaintenanceAn MCP server that exposes job-search and application-management capabilities to compatible AI clients, enabling discovery of vacancies, drafting of tailored application materials, and coordinated human-approved submissions.MIT
- AlicenseNot gradedqualityDmaintenanceMCP server that aggregates and deduplicates job listings from multiple public sources, ranks them against a user's resume, and exposes tools for searching, viewing details, explaining fit, and tracking applications.MIT
- FlicenseAqualityDmaintenanceEnables searching job listings, tracking applications, managing resumes, and tailoring resumes to job posts, all locally via MCP.20-