JO
Search

Job Searcher MCP Server: Time, Keywords, Remote Filters

Find job listings fast with this MCP server using time filters, keyword search, and remote-work options to surface relevant opportunities.

View on GitHub

Overview

The Job Searcher MCP Server is a small HTTP/MCP-compatible service that helps applications and LLMs find job listings quickly using time-based filters, keyword matching, and remote-work flags. It exposes a concise set of endpoints (or MCP tools) that accept structured queries and return filtered job results, making it easy to integrate into chatbots, notification systems, or custom search UIs.

Designed for developer integration, the server focuses on fast filtering and predictable JSON output. Rather than replacing a full job aggregation stack, it provides a programmable layer to apply common search criteria (e.g., posted within N days, contains keywords, remote-only) and return normalized results suitable for downstream processing or display.

Features

  • Time-range filters (e.g., last 24 hours, 7 days, 30 days)
  • Keyword search across title, description, and tags
  • Remote/onsite/hybrid filtering
  • Pagination and result limiting
  • JSON API compatible with MCP-style tool registration (easy to plug into LLM toolchains)
  • Health and metadata endpoints for service discovery
  • Configurable data sources and basic caching

Installation / Configuration

Clone the repository and install dependencies (Python example). Adjust commands if the project uses another language/runtime.

# clone
git clone https://github.com/0xDAEF0F/job-searchoor.git
cd job-searchoor

# install (example for Python)
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Basic environment configuration (example .env):

# .env
PORT=8080
DATA_SOURCE=local_jobs.json          # or an endpoint/DB connection string
CACHE_TTL=60                         # seconds
DEFAULT_PAGE_SIZE=20

Run the server locally:

export $(cat .env | xargs)
python -m job_searchoor.server
# or
uvicorn job_searchoor.server:app --host 0.0.0.0 --port ${PORT}

Docker usage (example Dockerfile + docker-compose):

docker-compose.yml

version: '3.7'
services:
  job-searcher:
    image: job-searchoor:latest
    build: .
    ports:
      - "8080:8080"
    environment:
      - PORT=8080
      - DATA_SOURCE=/data/jobs.json
    volumes:
      - ./data:/data:ro

Configuration options (common keys):

KeyTypeDescription
PORTintHTTP port to listen on
DATA_SOURCEstringPath or URL for job data source
CACHE_TTLintCache time-to-live in seconds
DEFAULT_PAGE_SIZEintDefault number of results per page

Available Tools / Resources

The server exposes a small set of HTTP endpoints suitable for MCP tool registration or direct API use:

  • GET /health
    • Returns basic health and version metadata.
  • POST /search
    • Main search endpoint. Accepts JSON body with filters and returns matched jobs.
  • GET /job/{id}
    • Fetch a single job by ID.
  • GET /schema
    • Returns the JSON schema of the job object and search request format.

Example search request schema (summary):

{
  "keywords": "python backend",
  "time_window_days": 7,
  "remote": "remote",      // values: "remote", "onsite", "hybrid", "any"
  "page": 1,
  "page_size": 20
}

Example response (trimmed):

{
  "total": 124,
  "page": 1,
  "page_size": 20,
  "results": [
    {
      "id": "abc123",
      "title": "Backend Engineer (Python)",
      "company": "Acme",
      "location": "Remote",
      "posted_at": "2026-04-07T12:00:00Z",
      "url": "https://jobs.example/acme/abc123",
      "snippet": "We are hiring..."
    }
  ]
}

Use Cases

  • Chatbot: Integrate the /search endpoint as an MCP tool for an assistant so it can run structured job queries whenever a user asks for new openings (e.g., “Find remote Python jobs posted in the last week”).

    • Example: Assistant constructs a POST /search with {“keywords”:“data engineer”,“time_window_days”:7,“remote”:“remote”} and returns the top matches to the user.

  • Job Aggregator: Periodically poll multiple data sources into the configured DATA_SOURCE, then use the server’s search and paging to power a frontend listing with filters for time and remote status.

  • Alerting/Notifications: Run a cron job that calls /search for a saved query (keywords + remote flag) and notifies users when new matching jobs appear since the last check.

  • Filtering Microservice: Use the server as a lightweight filter layer within a larger pipeline—ingest raw job feeds, normalize records, then call the server to apply the business rules for freshness and remote status before indexing.

Examples

  1. Quick curl search for remote senior roles in past 7 days:
curl -X POST http://localhost:8080/search \
  -H "Content-Type: application/json" \
  -d '{"keywords":"senior","time_window_days":7,"remote":"remote","page":1}'
  1. Register as an MCP tool (pseudo-JSON for LLM tool registration):
{
  "name": "job_search",
  "description": "Search jobs by keywords, time window, and remote flag",
  "endpoint": "http://job-searcher.local/search",
  "schema": { /* /schema response */ }
}

Notes and Next Steps

  • Data source: The server expects a configurable source of job records. Provide a connector or pre-load a JSON/DB feed.
  • Extensibility: Add provider adapters, richer ranking, or authentication as needed for production deployments.
  • Testing: Use the /schema endpoint to validate request payloads and mock responses during integration.

Repository and source code: https://github.com/0xDAEF0F/job-searchoor

Tags:search