Skip to main content
Glama

MCP Job Search

by adamd9

MCP Job Search Node

This project implements a LinkedIn job scraper with persistent job indexing, deep scanning, and filtering capabilities. It scrapes LinkedIn job listings, performs detailed analysis of each job against a candidate profile using OpenAI, stores matches in a persistent job index, and exposes MCP-compatible HTTP endpoints.

Setup

  1. Copy .env.example to .env and fill in your credentials:
    LINKEDIN_EMAIL=your-linkedin-email@example.com LINKEDIN_PASSWORD=your-linkedin-password OPENAI_API_KEY=your-openai-api-key OPENAI_MODEL=gpt-4o DEEP_SCAN_CONCURRENCY=2 SMTP_HOST=smtp.example.com SMTP_PORT=587 SMTP_USER=your-smtp-username SMTP_PASS=your-smtp-password DIGEST_FROM=jobs@example.com DIGEST_TO=you@example.com TIMEZONE=Australia/Sydney
  2. Install dependencies with npm install (already done if cloned with node_modules).
  3. Create a plan.json file (or use the /plan endpoint) describing your profile, search terms and deep scan criteria.
  4. Start the server with npm start.

Core Features

  • Plan Driven Search: Define your profile, search terms and scan prompt in plan.json or via the /plan API.

Persistent Job Index

  • Storage: All scraped jobs are stored in a persistent JSON file (data/job-index.json).
  • Deduplication: Jobs are uniquely identified by LinkedIn job ID to prevent duplicate scanning.
  • Profile Change Detection: System detects when your profile changes and triggers rescans.
  • Metadata: Each job entry includes scan status, match score, and detailed information.
Job Index Structure

Each job in data/job-index.json keeps the basic listing data along with the results of the most recent deep scan:

{ "id": "123456", "title": "Full Stack Engineer", "company": "ExampleCo", "link": "https://linkedin.com/jobs/view/123456", "posted": "2025-06-09", "scanned": true, "scanDate": "2025-07-05T12:00:00+10:00", "matchScore": 0.85, "matchReason": "Good skills overlap with your profile", "description": "Full job description...", "requirements": ["Skill 1", "Skill 2"], "location": "Sydney, Australia", "salary": "$100k - $120k" }

After each deep scan the matchScore and matchReason are updated so you can see why a job was scored the way it was. When a job is rescanned (for example after updating your profile) you may choose to store multiple scores in an array so previous results are preserved:

{ "scanHistory": [ { "date": "2025-07-05T12:00:00+10:00", "score": 0.85, "summary": "Good skills overlap with your profile" }, { "date": "2025-07-10T12:00:00+10:00", "score": 0.88, "summary": "Profile updated with React experience" } ] }

Deep Scanning

  • Detailed Extraction: Visits each job posting to extract comprehensive details (description, requirements, salary).
  • AI Analysis: Uses OpenAI to analyze job details against your profile.
  • Match Scoring: Generates a match score (0-1) and explanation for each job.
  • Concurrency Control: Configurable number of concurrent scans to balance speed and resource usage.

API Endpoints

Plan Management
  • GET /plan – Retrieve the current plan.
  • POST /plan – Body { "description": "..." } to generate a plan from text using OpenAI.
  • PUT /plan – Update fields of the existing plan (profile, searchTerms, scanPrompt).
Job Scanning and Retrieval
  • GET /scan – Triggers a LinkedIn scrape and deep scan without sending an email digest.
    • What it does: Scrapes LinkedIn job listings, adds them to the job index, and performs deep scanning on new jobs.
    • When to use: When you want to update your job index without sending an email.
  • POST /rescan – Forces a deep rescan of all jobs in the index.
    • What it does: Re-evaluates all jobs against your current profile, even previously scanned ones.
    • When to use: After updating your profile or when you want fresh match scores.
  • GET /jobs – Returns all jobs from the index with powerful filtering options:
    • Parameters:
      • minScore=0.7 – Only return jobs with match score >= specified value (0-1)
      • scanned=true|false – Filter by scan status (completed or pending scan)
      • limit=10 – Limit the number of results returned
    • When to use: For browsing or filtering the job index in custom ways.
  • GET /job/:id – Returns detailed information for a specific job by ID.
    • What it does: Retrieves complete job details including description, requirements, match score, etc.
    • When to use: When you need to examine a specific job in detail.
Email Digests
  • GET /latest_matches – Returns job matches with score >= 0.7 from the job index.
    • What it does: Retrieves jobs that match your profile well (70% match or better).
    • When to use: To quickly check your best matches without scanning.
  • POST /send_digest – Body { "email": "you@example.com" }. Scrapes, deep scans, and emails the matches.
    • What it does: Complete workflow - scrapes LinkedIn, updates index, deep scans jobs, and sends email digest.
    • When to use: When you want to receive an email with your latest job matches.

Workflow Examples

Initial Setup Workflow

  1. Configure your .env file with LinkedIn credentials
  2. Create your plan.json (or POST to /plan) with profile and search terms
  3. Start the server: npm start
  4. Trigger initial scan: npm run test:scan
  5. Wait for deep scanning to complete
  6. View matched jobs: npm run test:jobs:matched

Daily Usage Workflow

  1. Server automatically runs daily scan at 07:00 AEST and emails digest
  2. Alternatively, manually trigger scan: npm run test:scan
  3. Check latest matches: npm run test:latest
  4. View specific job details: ID=job_id npm run test:job

Profile Update Workflow

  1. Update your plan.json (or use PUT /plan) with new skills or search terms
  2. Force rescan of all jobs: npm run test:rescan
  3. View updated matches: npm run test:jobs:matched

Testing Commands

The project includes comprehensive test commands for both real and mock data scenarios:

Unit Tests

# Run all unit tests (using test fixtures, not live scraping) npm run test:unit

Endpoint Testing with Real Data

# Start the server first npm start # Trigger LinkedIn scraping and deep scanning (no email) npm run test:scan # Force deep rescan of all jobs in the index npm run test:rescan # Get all jobs from the index (formatted JSON output) npm run test:jobs:all # Get jobs with match score >= 0.7 npm run test:jobs:matched # Get unscanned jobs only npm run test:jobs:unscanned # Get limited number of jobs (5) npm run test:jobs:limit # Get details for a specific job (set ID env var first) # Example: ID=4247412997 npm run test:job npm run test:job # Get latest matches (score >= 0.7) npm run test:latest # Trigger full workflow and send digest email # (update email in package.json first) npm run test:digest

Endpoint Testing with Mock Data

# Test scan endpoint with mock data npm run test:scan:mock # Test rescan endpoint with mock data npm run test:rescan:mock # Test digest email with mock data npm run test:digest:mock

Configuration

The application uses a configuration system that combines settings from:

  1. Default values in code
  2. config.json file in the project root
  3. Environment variables (which take precedence)

Configuration File

You can edit the config.json file to set persistent configuration options:

{ "mockMode": false, "openaiModel": "gpt-4o", "deepScanConcurrency": 2, "timezone": "Australia/Sydney", "jobIndexPath": "data/job-index.json" }

Key Configuration Options

  • mockMode: When set to true, the system uses mock data instead of real scraping/scanning
  • openaiModel: The OpenAI model to use for job matching
  • deepScanConcurrency: Number of concurrent deep scans to perform
  • timezone: Timezone for cron scheduling
  • jobIndexPath: Path to the job index file

How Mock Data Works

Mock data testing uses pre-defined fixtures instead of live LinkedIn scraping:

  1. Mock LinkedIn Search Results: test/fixtures/linkedin-search-results.json
    • Contains sample job listings as if scraped from LinkedIn
    • Used by the /scan endpoint when mock mode is enabled
  2. Mock Job Details: test/fixtures/linkedin-job-details.json
    • Contains detailed job information as if deep-scanned
    • Used by the /rescan endpoint when mock mode is enabled

To enable mock mode, you can either:

  1. Set mockMode: true in config.json (persistent setting)
  2. Set the MOCK_DATA=true environment variable (temporary override)
  3. Use the test commands with :mock suffix which set the environment variable automatically

Automated Tasks

The daily cron task runs at 07:00 AEST and automatically:

  1. Scrapes LinkedIn for new job listings
  2. Updates the job index with new jobs
  3. Deep scans any new or unscanned jobs
  4. Sends an email digest to the configured recipient

Data Storage

  • Job Index: data/job-index.json - Persistent storage of all jobs with metadata. See Job Index Structure for the fields stored with each job. The file also records lastScanDate and a profileHash so the system can detect when a rescan is needed.
  • Daily Matches: data/YYYY-MM-DD.json - Daily snapshots of matched jobs (legacy format)
  • Screenshots: screenshots/ - Job posting screenshots captured during deep scanning (for debugging)
  • Plan: plan.json - Defines profile text, search terms and deep scan prompt.
-
security - not tested
F
license - not found
-
quality - not tested

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Helps users find suitable LinkedIn job opportunities by automatically scraping listings, analyzing compatibility with user profiles using AI, and sending custom match reports via email.

  1. Setup
    1. Core Features
      1. Persistent Job Index
      2. Deep Scanning
      3. API Endpoints
    2. Workflow Examples
      1. Initial Setup Workflow
      2. Daily Usage Workflow
      3. Profile Update Workflow
    3. Testing Commands
      1. Unit Tests
      2. Endpoint Testing with Real Data
      3. Endpoint Testing with Mock Data
    4. Configuration
      1. Configuration File
      2. Key Configuration Options
    5. How Mock Data Works
      1. Automated Tasks
        1. Data Storage

          Related MCP Servers

          • -
            security
            A
            license
            -
            quality
            A Model Context Protocol (MCP) server that provides tools to interact with LinkedIn's Feeds and Job API. You can do "search for 3 data engineer jobs in . For each job check if it a good match for me by analyzing it against my resume in file resume.md."
            Last updated -
            2
            31
            Python
            The Unlicense
          • -
            security
            F
            license
            -
            quality
            A Model Context Protocol server that enables seamless interaction with LinkedIn for job applications, profile retrieval, feed browsing, and resume analysis through natural language commands.
            Last updated -
            10
            Python
          • -
            security
            A
            license
            -
            quality
            Enables AI assistants to interact with LinkedIn data through the Model Context Protocol, allowing profile searches, job discovery, messaging, and network analytics.
            Last updated -
            1
            TypeScript
            MIT License
            • Apple
          • A
            security
            A
            license
            A
            quality
            Provides tools to interact with the HireBase Job API, enabling users to search for jobs using various criteria and retrieve detailed job information through natural language.
            Last updated -
            2
            2
            Python
            MIT License
            • Apple
            • Linux

          View all related MCP servers

          MCP directory API

          We provide all the information about MCP servers via our MCP API.

          curl -X GET 'https://glama.ai/api/mcp/v1/servers/adamd9/mcp-jobsearch'

          If you have feedback or need assistance with the MCP directory API, please join our Discord server