jobjourney

🚀 JobJourney Claude Plugin

A production-ready MCP server for JobJourney with AI job-search tools, local job discovery, and scheduled scraping from Claude.

---

✨ What It Does

• 🤖 AI job-search workflows for resume fit scoring, cover letters, CV generation, interview prep, and career chat
• 🗂️ Application tracking with saved jobs, notes, status changes, starring, search, and dashboard analytics
• 🔍 Local job discovery with a canonical discovery engine that stores results in local SQLite
• 🌐 Mixed scraping strategy: LinkedIn uses direct HTTP guest scraping, while blocked sites like SEEK use Playwright
• 🏢 ATS expansion for supported providers like Greenhouse and Lever after discovery
• ⏰ Scheduled discovery through the background agent and MCP tools
• 💾 Local storage for jobs, runs, schedules, and discovery reports in ~/.jobjourney/jobs.db

---

📸 Demo

Use it naturally from Claude:

"Use discover_jobs with keyword full stack, location Sydney, sources linkedin and seek, pages 1."

"Use search_jobs and show me the latest LinkedIn roles in Sydney."

"Use schedule_discovery to run every day at 9am for backend jobs in Melbourne."

"Evaluate how well my resume matches this job and draft a cover letter."

If you want product screenshots or GIFs later, this is the right place to add them.

---

📦 Installation

Option A: Claude Code

claude mcp add jobjourney \
  -e JOBJOURNEY_API_URL=https://server.jobjourney.me \
  -e JOBJOURNEY_API_KEY=jj_your_api_key_here \
  -e TRANSPORT=stdio \
  -- npx -y jobjourney-claude-plugin@latest

Option B: Claude Desktop

Add this to your Claude Desktop config file (claude_desktop_config.json):

{
  "mcpServers": {
    "jobjourney": {
      "command": "npx",
      "args": ["-y", "jobjourney-claude-plugin@latest"],
      "env": {
        "JOBJOURNEY_API_URL": "https://server.jobjourney.me",
        "JOBJOURNEY_API_KEY": "jj_your_api_key_here",
        "TRANSPORT": "stdio"
      }
    }
  }
}

Playwright prerequisite

For local browser-backed sources like SEEK, install a browser once:

npx playwright install chromium

---

🚀 Quick Start

1. Connect the plugin

claude mcp add jobjourney \
  -e JOBJOURNEY_API_URL=https://server.jobjourney.me \
  -e JOBJOURNEY_API_KEY=jj_your_api_key_here \
  -e TRANSPORT=stdio \
  -- npx -y jobjourney-claude-plugin@latest

2. Log in to browser-backed sites when needed

From Claude:

Use login_jobsite with site "seek"

3. Run discovery

From Claude:

Use discover_jobs with keyword "full stack", location "Sydney", sources ["linkedin", "seek"], pages 1

4. Query the stored results

Use search_jobs with source "linkedin" and limit 5

5. Schedule it

Use schedule_discovery with keyword "full stack", location "Sydney", time "09:00", sources ["linkedin", "seek"]

---

🔍 Source Support

Source	Status	Transport	Notes
linkedin	Active	HTTP guest scraping	Primary supported LinkedIn path
seek	Active	Playwright	Local browser session support
indeed	Planned	Playwright	Not implemented yet
jora	Planned	Playwright	Not implemented yet

ATS	Support
greenhouse	Detect + expand
lever	Detect + expand
workday	Detect only
smartrecruiters	Detect only
ashby	Detect only

---

🧠 How Local Discovery Works

The local discovery engine lives under src/discovery and uses one canonical job model across all sources.

LinkedIn

1. Fetch guest search results
2. Fetch guest job detail HTML for each posting
3. Extract description, metadata, and external apply URL
4. Detect ATS from the external URL
5. Expand supported ATS companies

SEEK

1. Launch Playwright
2. Use the browser-backed source flow
3. Normalize results into the same canonical job schema

Storage

Local runs are stored in:

• jobs DB: ~/.jobjourney/jobs.db
• agent heartbeat: ~/.jobjourney/agent-heartbeat.json

The database stores:

• discovered jobs
• scrape/discovery runs
• schedules

---

🛠 Key Tools

This MCP exposes a broad JobJourney toolset. For local discovery, these are the most important ones: