Job Search Tool

Local-first job search automation: collect jobs from multiple boards, score them against your own criteria, store them in SQLite, review them in a React dashboard, query them through REST, and expose the same data to MCP clients.

Features

• Multi-board ingestion through JobSpy.

• Configurable keyword scoring with separate save and notification thresholds.

• SQLite persistence with bookmarks, applied state, blacklist, and retention.

• React dashboard for review, filtering, analytics, cleanup, and CSV export.

• Local semantic search through ChromaDB's bundled ONNX embedder.

• Telegram notifications for high-scoring new jobs.

• Unified ASGI web server for dashboard, REST API, and MCP.

• Docker Compose deployment with localhost-first network defaults.

Related MCP server: jobs-winterchill-mcp

Docker Quick Start

1. Create your runtime configuration:

   cp config/settings.example.yaml settings.yaml

2. Edit settings.yaml, especially locations, queries, scoring, and optional Telegram settings.

3. Start the scheduler and web server:

   docker compose up -d

4. Open the dashboard:

   http://127.0.0.1:8501

The same web process exposes REST at http://127.0.0.1:8501/api and MCP at http://127.0.0.1:8501/mcp. Published ports bind to 127.0.0.1 by default. For trusted LAN use, set JOB_SEARCH_WEB_BIND=0.0.0.0 in .env and keep firewall rules tight.

Interfaces

Documentation

• Docker deployment

• Configuration

• REST API

• MCP server

• Operations

• Architecture

• Testing

• Release process

Local Development

uv sync
npm --prefix frontend install
cp config/settings.example.yaml config/settings.yaml
uv run pytest
npm --prefix frontend run test
uv run pre-commit run --all-files

Local commands run through installed package entrypoints:

uv run job-search once
uv run job-search scheduler
uv run job-search-web

Releases

Docker images are published to Docker Hub by the release workflow when a v* tag is pushed. Release tags produce semver tags, latest, SBOM, and provenance metadata for vincenzoimp/job-search-tool.

License

MIT. See LICENSE.