job-search-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@job-search-mcp Find AI Engineer roles in Warsaw"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Related MCP server: Job Assistant MCP
Tools
Tool | Description |
| Searches justjoin.it listings. Returns title, company, URL, salary, tags, location. |
| Fetches a single job offer page and returns a cleaned-up description plus tech stack tags. |
| Saves/updates an application's status locally. |
| 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 buildThis 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.jsOr 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βbuildSearchUrlagainst known/unmapped/diacritic city names, andparseOfferCards/parseJobDetailsagainst 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/listApplicationsagainst a temp file (via theJOB_SEARCH_STORE_PATHenv 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.tsanchors on stable landmarks instead: theoffer_list_offer_title_linkclass, 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/JobPostingJSON-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, notwarsaw) βsearch_jobsmaps 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, soString.normalize("NFD")doesn't strip it the way it doesΓ³orΕΊβ it needs an explicitΕ/Εβl/Lreplacement 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_detailswill 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.
Available Tools
2 toolsget_job_detailsGet Job DetailsA
Fetch a single justjoin.it job posting and return a cleaned-up description and tech stack tags.
Inputs: url (required).
track_applicationTrack ApplicationB
Save or update the application status for a job posting in the local tracker.
Inputs: url (required), status (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
TDQS
Scored across 2 tools
The two tools have clearly distinct purposes: one fetches job details, the other tracks applications. No overlap or confusion.
Both tool names follow a consistent verb_noun pattern: 'get_job_details' and 'track_application'.
With only 2 tools for a 'job-search-mcp', the scope is far too narrow. A job search server typically needs search, list, and filter capabilities.
The tool surface is severely incomplete for a job search server. There is no way to discover or search for jobs, only view details of a known posting and track application status.
Related MCP Connectors
Track job applications on a board: let Claude or ChatGPT read and update jobs, interviews, notes.
Job search tracker for Claude and ChatGPT: applications, interviews, follow-ups, company watch.
Job search for your AI: save jobs, research companies, keep stories, track applications.
Analyze job listings against your resume, track applications, and generate cover letters.
Related MCP Servers
- FlicenseNot gradedqualityBmaintenanceEnables automated job searching from multiple boards, filtering matches against saved criteria, deduplicating seen postings, and tracking application statuses. Runs locally and integrates with Claude Desktop for natural-language queries and updates.-
- AlicenseAqualityCmaintenanceEnables Claude to search public DOU and Djinni job postings concurrently, score each result against a stored profile with explainable skill, role and seniority matching, and track applications through a SQLite-backed pipeline. Also supports saving jobs, updating statuses, and generating tailored cover letters and talking points.8MIT
- AlicenseNot gradedqualityBmaintenanceEnables Claude to read and update the local job-search tracker, adding postings from screenshots, pasted text or links, drafting application emails, syncing Gmail to log sent applications and replies, and answering questions about what's due or which jobs match a criteria. Every change is validated and appears live on the dashboard with a timeline entry.MIT
- AlicenseBqualityBmaintenanceEnables Claude to search job listings on selected sites, filter and score them against your own skills, track application status, and generate a tailored LaTeX/PDF resume for each job. It also supports importing an existing Word or PDF resume and diagnosing local setup, all with data kept in a private folder on your own machine.12MIT