Job Hunt Copilot (MCP server)

An MCP (Model Context Protocol) server that turns any MCP-capable AI app into a personal job-search assistant. You paste your resume and job postings; the server stores them, matches skills, tracks applications, and shows which skills the market asks for most.

Designed to work with any MCP client. Tested with MCP Inspector and the included client using OpenAI. The Anthropic and Gemini adapters and the Claude Desktop config are included but not yet tested.

Architecture

You -> AI model (Claude / OpenAI / Gemini)
          | tool calls
          v
      MCP client (Claude Desktop, Cursor, or client/chat_client.py)
          | MCP over stdio
          v
      MCP server (jobhunt/server.py)  ->  core.py  ->  SQLite (data/jobhunt.db)

• jobhunt/core.py holds all the logic and has no MCP code, so it is unit tested on its own.

• jobhunt/server.py is a thin MCP layer exposing tools, resources and prompts.

• client/chat_client.py is a client showing how tool calling works with three model providers.

Related MCP server: CareerPilot

What the server exposes

Setup

python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env             # add your API key(s); never commit .env
python -m unittest discover -s tests -v   # core logic tests

Try it three ways

1. MCP Inspector (no AI needed; best for debugging)

npx @modelcontextprotocol/inspector python -m jobhunt.server

Call save_resume with the text from data/sample_resume.txt, then add_job_from_text with data/sample_job.txt, then match_resume_to_job.

2. The included client (uses your API key)

python client/chat_client.py --provider anthropic   # or openai / gemini

Then chat, for example: "Save this resume: ..." then "Save this job: ..." then "How well do I match job 1?"

3. Claude Desktop - add this to its MCP config file (use absolute paths, and the Python from your venv):

{
  "mcpServers": {
    "job-hunt-copilot": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["-m", "jobhunt.server"],
      "cwd": "/absolute/path/to/job-hunt-copilot"
    }
  }
}

Restart the app. If your version ignores cwd, set "env": {"PYTHONPATH": "/absolute/path/to/job-hunt-copilot"} instead.

Design decisions

• Manual paste as the job source. Big job sites restrict scraping and lack open search APIs, so the server takes text you paste. A future JobSource adapter can add official feeds.

• Honest tailoring. get_tailoring_context returns rules telling the model to reword real experience only.

• Work-pass hints, not decisions. Postings mentioning citizens, PR or work passes are flagged; you decide.

• Rough matching. The score uses a keyword skill list (jobhunt/skills.py). It is transparent and testable, but it misses skills outside the list. Semantic matching with embeddings is a planned upgrade.

• Privacy. Data stays in a local SQLite file, git-ignored. Use sample data in public demos.

• MCP SDK version. The code targets the MCP Python SDK v1, so requirements.txt pins mcp<2. Version 2 renamed FastMCP, so a migration is needed before upgrading.

Known limitations

• Keyword matching only. The score counts skills from a fixed list, so a posting that uses concepts instead of technology names can show a misleadingly high score (a 100% result on a role with few recognized skills). Semantic matching is planned.

• AI output needs review. Even with rules in get_tailoring_context, models sometimes stretch claims in suggested resume bullets and then report that they were unsure of nothing. Always check suggestions against your real resume.

• No duplicate detection. Saving the same posting twice creates two jobs; use delete_job to clean up.

• Applied date is today's date. track_application cannot record an earlier date yet.

• Privacy. When an AI client calls tools, your resume text is sent to that AI provider.

Roadmap

• Semantic matching with embeddings

• Email-alert import (parse JobStreet / LinkedIn / Indeed alert emails)

• JobSource adapters for open job feeds

• Streamable HTTP transport + auth, deployed remotely

• Evaluation: compare the match score with a human rating on 20 real postings