Job Search MCP Server

An MCP (Model Context Protocol) server that lets Claude search justjoin.it job postings and track your applications, so you can ask things like "find me new AI Engineer roles in Warsaw" or "what's the status of the application I sent last week" directly in a chat with Claude Desktop or Claude Code.

Why

Built as a hands-on MCP project for my own AI Engineer job search — real tool, real use, not a toy demo.

Tools

Tool	Description
search_jobs(keyword, location?)	Searches justjoin.it listings. Returns title, company, URL, salary, tags, location. location accepts a city name ("Warsaw", "Krakow", ...) or "remote".
get_job_details(url)	Fetches a single job offer page and returns a cleaned-up description plus tech stack tags.
track_application(url, status)	Saves/updates an application's status locally. status is one of saved, applied, interviewing, rejected, offer.
list_applications()	Lists all tracked applications, most recently updated first.

Application data is stored locally in a JSON file at ~/.job-search-mcp/applications.json — no database, no external service.

Setup

Requires Node.js 18+.

git clone <this-repo-url>
cd job-search-mcp
npm install
npm run build

This produces dist/index.js, a stdio MCP server.

Connecting to Claude Desktop

Add the server to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS), replacing the path below with the absolute path to dist/index.js in your clone (run pwd inside the project directory to get it):

{
  "mcpServers": {
    "job-search": {
      "command": "node",
      "args": ["/absolute/path/to/job-search-mcp/dist/index.js"]
    }
  }
}

Restart Claude Desktop. The four tools above should appear as available tools (look for the 🔨 tools icon in the chat input).

Connecting to Claude Code

claude mcp add job-search -- node /absolute/path/to/job-search-mcp/dist/index.js

Or add it to a project's .mcp.json:

{
  "mcpServers": {
    "job-search": {
      "command": "node",
      "args": ["/absolute/path/to/job-search-mcp/dist/index.js"]
    }
  }
}

Example prompts

• "Find AI Engineer roles in Warsaw"
• "Get me the full details and tech stack for this listing: <url>"
• "Mark that job as applied"
• "What's the status of all my job applications?"
• "Show me everything I've marked as interviewing"

Development

npm run dev    # tsc --watch
npm run build  # one-off compile
npm start      # run the compiled server directly (for manual stdio testing)
npm test       # build, then run the test suite (node's built-in test runner)

Tests

Tests run with Node's built-in test runner (node:test) — no extra test framework dependency. npm test compiles first, then runs everything under dist/**/*.test.js.

• justjoin.test.ts — buildSearchUrl against known/unmapped/diacritic city names, and parseOfferCards/parseJobDetails against trimmed-but-verbatim fixtures of real justjoin.it markup (including the <object> logo wrapper that makes the tag-pill parsing heuristic necessary), so the parsing logic is verified without hitting the live site.
• store.test.ts — trackApplication/listApplications against a temp file (via the JOB_SEARCH_STORE_PATH env var override), so tests never touch your real ~/.job-search-mcp/applications.json.

Tricky bits

• justjoin.it has no public API. It's a Next.js app that server-renders offer cards, but the CSS classes are build-hashed (e.g. mui-1cks7or) and change on every deploy, so scraping can't rely on fixed selectors. src/justjoin.ts anchors on stable landmarks instead: the offer_list_offer_title_link class, Lucide icon classes (svg.lucide-map-pin, svg.lucide-building), and — for the tag pills, where even sibling/depth assumptions turned out to be unreliable — a structural heuristic that detects "a <div> whose children are all plain-text, childless <div>s," a shape unique to that row on the card.
• Job detail pages are easier: they embed proper schema.org/JobPosting JSON-LD, which is used for title/company/location/salary/employment type. The visible HTML is still used for the description and tech stack, since the JSON-LD description is a single run-on string with no paragraph breaks.
• City slugs are Polish-only (warszawa, not warsaw) — search_jobs maps common English city names to their Polish slugs. Writing the test for this caught a real bug: Polish ł (as in Łódź) isn't a combining-mark diacritic, so String.normalize("NFD") doesn't strip it the way it does ó or ź — it needs an explicit ł/Ł → l/L replacement first.
• Salary is often undisclosed. Both tools fall back to "Not specified" rather than erroring when a listing doesn't list a salary.
• Scraping is inherently brittle. If justjoin.it changes its page structure enough to break these heuristics, search_jobs/get_job_details will return an explicit tool error rather than silently returning garbage.

Roadmap (not yet built)

• match_score(job_url) — score a job description against a CV/skills profile via the Anthropic API, with a rationale.
• A second job board as a data source, so results aren't tied to justjoin.it alone.