<div align="center">

🎯 open-job-hunter

An open-source MCP server that discovers and AI-evaluates job offers against your profile — running 100% locally.

No cloud, no data leaving your machine, no vendor lock-in. You describe yourself once in a config file, and the server scores every job posting against you, keeps a pipeline, and can email you a daily digest of the best matches.

Public beta testing guide · Send beta feedback

</div>

Code signing policy

Code signing through SignPath Foundation has been requested and is pending approval. The current v1.2.2 Windows executables are unsigned. See SignPath.io for information about the signing service.

If the request is approved, every signing request will require manual approval and must originate from the repository's verifiable release workflow. See the complete Code signing policy, Privacy policy and Security policy.

---

Why

Job searching at a senior level is a matching problem drowning in noise. You are one of hundreds of applicants per role, and most of your time is spent reading postings that were never a fit. open-job-hunter flips that: it pulls openings from multiple job boards, runs each one through a local LLM that scores it against your real background, and surfaces only the offers worth your time — with the risks and the angle to pitch already written out.

Because evaluation happens on a local model (Ollama), your profile and your search never leave your computer.

Features

• Configurable candidate profile — one config/profile.json drives everything. The tool works for anyone, not a single person.
• Local AI evaluation — every offer is scored 0–100 with apply decision, detected_risks, strong_points_to_highlight, and a tailored custom_angle, via your own Ollama model.
• Multi-source discovery — Remotive, Greenhouse boards, and Lever boards out of the box, plus generic URL ingestion.
• Application pipeline — a local JSON database tracks every offer through states: nueva → evaluada → postulada → entrevista → oferta (and more).
• Scheduler + email digests — optionally run discovery on a schedule and receive the top matches by email (SMTP).
• Two interfaces — a standard MCP server (stdio) for use inside Claude / any MCP client, and an HTTP API bridge for dashboards and automation.

Architecture

                 ┌────────────────────────────────────────┐
   MCP client ──▶│  MCP server (stdio)                     │
  (Claude, etc.) │      evaluar_oferta_laboral             │
                 │      listar_pipeline_postulaciones       │──▶ Local JSON DB
   HTTP client ─▶│  HTTP bridge (:3000)                    │    (pipeline)
   / dashboard   │      /api/evaluar, /api/discovery/*      │
                 └───────────────┬─────────────────────────┘
                                 │ prompt built from
                                 ▼ config/profile.json
                        ┌──────────────────┐
                        │  Ollama (local)  │  ◀── your data stays here
                        └──────────────────┘

The complete engineering case study is documented in Architecture and decisions, including system diagrams, quality attributes, Architecture Decision Records (ADRs), threat boundaries and the AI-assisted delivery model.

Quickstart

Windows desktop app

Download the latest installer or portable build from GitHub Releases. No Node.js installation is required. The desktop app stores your profile and pipeline under your Windows user data directory.

Windows SmartScreen may warn because the current v1.2.2 Windows executables are unsigned. Verify the published SHA-256 checksum before running them. Code signing has been requested through SignPath Foundation and is pending approval.

Release integrity evidence includes SHA-256 manifests, a CycloneDX SBOM, Microsoft Defender scanning and GitHub/Sigstore attestations. See the security policy for verification commands.

To uninstall the installed edition, open Windows Settings → Apps → Installed apps, select Open Job Hunter, and choose Uninstall. The portable edition can be removed by closing it and deleting its executable. User-created profile and pipeline data are intentionally retained in the Windows user-data directory; see the Privacy policy for their location and deletion instructions.

Developer / MCP installation

Requires Node ≥ 20 and a running Ollama instance. The model needs roughly 5–6 GB of free RAM; the dashboard reports when Ollama or the model is missing instead of failing the evaluation.

# 1. Clone & install
git clone https://github.com/andminin-engineering/open-job-hunter.git
cd open-job-hunter
npm install

# 2. Pull a local model (any instruction model works)
ollama pull qwen2.5:7b

# 3. Create your profile
cp config/profile.example.json config/profile.json
#   ...then edit config/profile.json with your background (see below)

# 4. (optional) configure environment
cp .env.example .env

# 5. Build & run the web interface
npm start

Run npm run doctor after building to check paths, local data access, profile setup and Ollama readiness. It reports optional setup gaps as warnings and exits non-zero for broken installation requirements.

Configure your profile

This is the heart of the tool. The easiest way is the Mi perfil tab of the web interface, which starts with empty fields and saves to config/profile.json (or PROFILE_PATH). Evaluation stays blocked until you save your own profile. The Idioma de las respuestas setting controls the language of AI feedback; Idiomas que dominás describes your language skills. You can also copy the example and edit it by hand:

{
  "fullName": "Your Name",
  "headline": "Your Professional Headline",
  "summary": "A 2-3 sentence pitch of who you are and what you solve best.",
  "coreCompetencies": {
    "skills": ["Your most relevant skills"],
    "tools": ["Tools you use"]
  },
  "portfolioUrl": "https://github.com/your-handle",
  "languages": [{ "language": "English", "level": "B2" }],
  "search": {
    "keywords": "roles you want to find",
    "minScoreToApply": 70,
    "boards": { "greenhouse": ["stripe", "datadog"], "lever": ["lever"] }
  }
}

The evaluator prompt is generated from this file, so the more precise your competencies and summary, the sharper the scoring.

In Mis postulaciones, the main desktop board shows the four in-progress stages plus Con oferta and Rechazadas as six visible columns, each with its own scrollable list. On narrower screens the columns wrap into rows; the outcome buttons can also focus on one column at a time. Descartadas, Sin evaluar, and Otros estados have their own views. Con oferta displays the existing oferta state reached through ¡Recibí oferta!; it means an offer was received, not that it was formally accepted. Rechazadas and Descartadas display their existing states separately. Otros estados shows records saved by older versions without changing them. Search and sorting cover the full saved pipeline, while the dynamic Ver N más control loads the next matching page; the registered-vacancy counter reports the full total, not only the current page.

Synthetic functional-analyst dashboard test

To test the dashboard with more than 200 offers without using anyone's real pipeline, run the generator once per checkout. It creates 301 entirely fictitious offers, a fictitious analyst profile, and a disabled scheduler configuration under src/data/mock-analista-funcional/. These files are ignored by Git, and the generator refuses to replace an existing mock.

In PowerShell, from the repository root:

node scripts/generate-functional-analyst-mock.mjs # Skip if already generated
node node_modules/typescript/bin/tsc
$env:JOB_HUNTER_DATA_DIR = (Resolve-Path 'src/data/mock-analista-funcional').ProviderPath
$env:JOB_HUNTER_DB_PATH = Join-Path $env:JOB_HUNTER_DATA_DIR 'db.json'
$env:PROFILE_PATH = Join-Path $env:JOB_HUNTER_DATA_DIR 'profile.json'
$env:SCHEDULER_CONFIG_PATH = Join-Path $env:JOB_HUNTER_DATA_DIR 'scheduler-config.json'
$env:SCHEDULER_ENABLED = 'false'
$env:PORT = '3001'
node build/bin/http.js

Open http://127.0.0.1:3001. These overrides keep the demo database, profile, and scheduler configuration separate from the normal app data. The fixture intentionally includes eight legacy-state cards so the Otros estados view can also be tested. After stopping the server, close that PowerShell window (or remove the six environment variables) before launching your normal setup; otherwise that window will continue pointing at the mock.

Use as an MCP server

Point any MCP client at the built server. Example for Claude Desktop / Claude Code (mcp config):

{
  "mcpServers": {
    "open-job-hunter": {
      "command": "node",
      "args": ["/absolute/path/to/open-job-hunter/build/bin/mcp.js"]
    }
  }
}

MCP tools

| Tool | What it does | | --- | --- | | evaluar_oferta_laboral | Score a single job description against your profile. | | listar_pipeline_postulaciones | List stored offers, optionally filtered by state. | | actualizar_estado_postulacion | Move an offer to a new pipeline state. | | registrar_feedback_postulacion | Record recruiter feedback on an offer. |

HTTP API (selected endpoints)

| Method | Path | Purpose | | --- | --- | --- | | GET | /health | Liveness check. | | POST | /api/evaluar | Evaluate one offer. | | POST | /api/evaluar-lote | Evaluate a batch of offers. | | GET | /api/discovery/remotive | Discover jobs from Remotive. | | GET | /api/discovery/greenhouse | Discover jobs from a Greenhouse board. | | GET | /api/discovery/lever | Discover jobs from a Lever board. | | GET | /api/pipeline | Read a pipeline page; supports state filters, search, sorting and offset. Returns filtered total and unfiltered allTotal. | | POST | /api/scheduler/run-now | Trigger a discovery + digest cycle. |

Privacy

The LLM evaluation runs against a local Ollama instance — your profile, the offers you evaluate, and your pipeline stay on your machine. The only outbound calls are to the public job-board APIs you explicitly query, and (optionally) your own SMTP server for digests.

For the complete inventory of stored data, network interactions, retention and deletion instructions, read the Privacy policy.

Roadmap

• Additional job-board connectors (Ashby, Workable, LinkedIn export).
• Pluggable LLM backends beyond Ollama.
• Signed Windows builds and automatic updates.
• CV/offer gap analysis.

Contributing

Issues and PRs are welcome. This project started as a personal job-search tool and was generalized so anyone can use it — improvements that make it useful to more people are especially appreciated.

License

MIT © 2026 Andrea Minín