Job Search Apply MCP

Turn a job posting into a CV and cover letter you can actually send.

Give it a posting. It scores whether the job is worth your time, drafts a tailored CV and cover letter, has a second AI review the draft and strip any claim your profile does not support, compiles both to PDF, checks the pages are right and that an applicant tracking system can read them, and tracks what happened next.

It also finds the postings in the first place, and remembers everything it has already shown you.

Runs entirely on your own machine with the AI tools you already use: Claude Code, GitHub Copilot CLI, Claude Desktop, Cursor, or anything else that speaks MCP. No API keys, no server, no subscription.

Your files stay on your own computer. This project runs no service, has no account, and uploads nothing anywhere.

One honest caveat: it works through your AI assistant, so anything you ask that assistant to read is sent to whichever AI provider you already use, exactly as if you had pasted it into a chat with it. Your CV is stored locally, but if you ask the assistant to tailor it, the assistant sees it. See SECURITY.md.

How it works

      ┌────────────────────────────────────────────────────────┐
      │  ONE-TIME SETUP                                        │
      │                                                        │
      │   Install  ──▶  /setup  ──▶  edit jobsearch.config.json│
      │                 tells it        tells it what jobs     │
      │                 about YOU       you want               │
      └────────────────────────────────────────────────────────┘
                                │
                                ▼
      ┌────────────────────────────────────────────────────────┐
      │  EVERY WEEK                                            │
      │                                                        │
      │   /scrape  ──▶  /rank  ──▶  /apply <url>               │
      │   find new      score &     tailor CV + letter,        │
      │   postings      shortlist   check them, track it       │
      └────────────────────────────────────────────────────────┘
                                │
                                ▼
      ┌────────────────────────────────────────────────────────┐
      │  WHEN SOMETHING HAPPENS                                │
      │                                                        │
      │   /outcome <company>  ──▶  /interview <company>        │
      │   record the reply         prepare for the call        │
      └────────────────────────────────────────────────────────┘

Two halves, working together:

• The MCP server remembers things: every posting seen, every application sent, your profile. Your AI assistant queries it with ordinary questions.

• The workflows do the writing: evaluating a role, drafting a tailored CV and cover letter, checking them, and preparing you for the interview.

Related MCP server: mcp-autopilot-jobhunt

Is this for me?

You need to be comfortable copying a few commands into a terminal. You do not need to know what MCP is, own a server, or write any code.

There are two tiers, and the difference matters:

Why the difference: the drafting workflows are markdown instruction files in .claude/. Coding CLIs load that folder automatically and expose each file as a slash command. Desktop chat apps do not, so there you point the assistant at the file by hand. Same workflow, one extra line of typing.

If you are choosing, pick a coding CLI. The CV drafting is where the value is, and that is the tier where it runs by itself.

What you get

19 tools your AI assistant can call, covering the whole loop:

• search job portals and remember everything already seen, so you never read the same posting twice

• pull a posting's full text and work out whether it is genuinely remote and what it pays

• check a role against your own hard limits (salary floor, where you are willing to work) with a deterministic yes/no, not a vibe

• score and shortlist a batch of postings

• track applications from drafted to offer or rejection

• store and search your own profile: experience, skills, interview stories

Plus a set of guided workflows (/apply, /scrape, /rank, /interview and more) that turn a job posting into a tailored, compiled, proofread CV and cover letter. See docs/WORKFLOWS.md.

The value is in the drafting. A reviewer agent critiques every draft before you see it, and a grounding audit strips any claim your profile does not actually support, so the CV cannot quietly invent things about you.

Quick start

Three steps. Budget about ten minutes.

1. Install

Windows: use PowerShell (press Start, type "PowerShell"). macOS: use Terminal (Cmd+Space, type "Terminal").

You need two things:

• Python 3.10 or newer. Check with python --version on Windows, python3 --version on macOS. If missing, get it from python.org and tick "Add Python to PATH" in the Windows installer, or it will not be found later.

• Git. Check with git --version. If missing, get it from git-scm.com, or skip it by downloading this project as a ZIP from GitHub ("Code" → "Download ZIP") and unzipping it.

git clone https://github.com/treymorgan/jobsearch-apply-mcp.git
cd jobsearch-apply-mcp
pip install -e .

On macOS and Linux use pip3 if pip is not found.

Check it installed:

jobsearch-mcp --check

That prints where everything resolved to and flags anything wrong. It is the fastest way to confirm the install before touching your AI app's config.

Some systems protect the system Python. Use a virtual environment:

python3 -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -e .

Note the interpreter path, you may need it in step 3:

2. Tell it what you are looking for

cp jobsearch.config.example.json jobsearch.config.json

On Windows Command Prompt use copy instead:

copy jobsearch.config.example.json jobsearch.config.json

(PowerShell accepts cp.)

Open jobsearch.config.json in any text editor and change the search terms to job titles you actually want. Everything in the file is optional and explained inline. Full reference: docs/CONFIGURATION.md.

3. Connect it to your AI app

Pick your app below, then restart it.

Claude Code, from inside the cloned folder:

claude mcp add jobsearch -- jobsearch-mcp

GitHub Copilot CLI, edit your MCP config:

{
  "mcpServers": {
    "jobsearch": {
      "type": "local",
      "command": "jobsearch-mcp",
      "env": { "JOBSEARCH_HOME": "/full/path/to/jobsearch-apply-mcp" },
      "tools": ["*"]
    }
  }
}

With either of these, run the workflows by typing /setup, /scrape, /apply directly. Open the project folder in the CLI so it finds .claude/.

Edit the config file directly:

Or from inside the app: Settings → Developer → Edit Config. Paste this in, replacing the path with the folder you cloned into:

{
  "mcpServers": {
    "jobsearch": {
      "command": "jobsearch-mcp",
      "env": { "JOBSEARCH_HOME": "/full/path/to/jobsearch-apply-mcp" }
    }
  }
}

On Windows the path looks like C:\\Users\\you\\jobsearch-apply-mcp (double backslashes are required in JSON).

If jobsearch-mcp is not found, use the full Python path instead:

{
  "mcpServers": {
    "jobsearch": {
      "command": "python",
      "args": ["-m", "jobsearch_mcp.server"],
      "env": { "JOBSEARCH_HOME": "/full/path/to/jobsearch-apply-mcp" }
    }
  }
}

Claude Desktop does not read the .claude/ folder, so /setup and the other slash commands do not exist there. You get the 19 data tools, and you start each workflow by pasting its instruction file path (see Using it below).

Create .cursor/mcp.json in your project, using the same shape as the Claude Desktop example above. Same caveat: data tools yes, slash commands no.

These connect to MCP servers over remote HTTP only. They cannot launch a local program, which is how this project normally runs.

To use them you would have to host the server yourself, with a public HTTPS address and authentication, as described in docs/HOSTING.md. That is a real amount of work, and even then you would get the data tools without the drafting workflows, which is the part most people want.

For a laptop, use a coding CLI instead. Hosting is worth it mainly if you want to reach your job search from a phone.

Check it worked

Ask your AI assistant:

Use the jobsearch config_status tool and show me the result.

You should get back a summary of your settings. If you do, you are done. Then try:

Search for jobs using the jobsearch tools and show me what is new.

Something wrong? See docs/TROUBLESHOOTING.md.

Using it: a worked example

Setup told the server how to run. This tells it about you, and then puts it to work. Talk to your AI assistant in the project folder in plain English.

Step 1: Tell it about yourself (once, about 15 minutes)

Drop whatever you already have into the documents/ folder first. It saves a lot of typing:

Then say:

/setup

It reads what you provided, asks about anything missing, and writes your profile to the profile/ folder. If you have nothing to upload, it just interviews you instead.

Everything it writes is gitignored. Your name, phone number and salary expectations never get committed.

Step 2: Tell it what you are looking for

/setup fills in jobsearch.config.json for you, but it is a plain text file and you should check it. Open it and confirm the search terms match how jobs you want are actually advertised:

{
  "search": {
    "queries": ["registered nurse", "clinical nurse specialist"],
    "remote_location": "United States",
    "local_location": "Denver, Colorado, United States",
    "local_metro": ["denver", "boulder", "aurora"]
  },
  "deal_breakers": {
    "salary_floor": 85000
  }
}

That example says: search remote roles across the US, and anything in the Denver area where commuting is fine, and treat anything under $85,000 as a no.

Leave local_metro empty if you only want remote work. Every field is optional and explained in docs/CONFIGURATION.md.

Check it took effect:

Run the jobsearch config_status tool.

Step 3: Find jobs

/scrape

Searches the job boards, drops anything you have already seen, and shows what is new. Run it every few days; it only ever shows you new postings.

/rank

Scores that batch against your profile and hands back a shortlist, so you are not reading a forty-row table by hand.

You can also just ask normally:

Any new remote jobs over $100k that I have not looked at yet?

Step 4: Apply to one

/apply https://example.com/jobs/12345

This is the part that saves real time:

1. Reads the posting and scores your fit, then stops and asks whether to continue. It will tell you when a job is not worth applying to.

2. Drafts a CV and cover letter tailored to that posting.

3. A second AI reviews the draft with fresh eyes, researches the company, and strips any claim your profile does not actually support. It cannot invent achievements for you.

4. Compiles both to PDF, looks at the result, and fixes layout problems. The CV comes out at exactly two pages, the letter at one.

5. Checks the PDF is machine-readable, so an applicant tracking system does not silently discard you.

6. Records it in your tracker.

You get two PDFs to read and send. Always read them before sending.

Step 5: Keep track

/outcome Acme Corp

Records what happened: heard nothing, got an interview, rejected, offered. It also drafts follow-up emails for applications that have gone quiet.

/interview Acme Corp

Builds a preparation pack for the specific stage you have reached, using the CV you actually sent, and will run a mock interview if you want one.

What a normal week looks like

Monday      /scrape        see what is new
            /rank          get the shortlist
Tuesday     /apply <url>   apply to the best two or three
Thursday    /outcome       record any replies
As needed   /interview     prepare when you get a call

Full detail on every command: docs/WORKFLOWS.md.

If you do not have slash commands

On Claude Desktop, Cursor and other chat clients, /setup and friends do not exist. The workflows still run: point the assistant at the instruction file.

Note the two folders. Most workflows are commands; three are skills.

Everything else is under .claude/commands/ with a matching filename.

Because the assistant has to read the file each time, this is more typing and uses more of your context than a coding CLI, which is why a CLI is the recommended path.

Optional extras

None of these are required. Add them when you want the feature.

Where your data lives

Nothing leaves your machine unless you deliberately host the server yourself.

The files under .claude/skills/job-application-assistant/ are blank templates and stay tracked. Your real answers go to profile/, which is gitignored, so forking this repo cannot publish your details by accident.

This is enforced rather than just documented: python3 tools/security_guards.py fails if any of those ignore rules is removed. See SECURITY.md.

Documentation

Job boards

Search picks Adzuna automatically when a key is present, and falls back to freehire otherwise, saying so in the results. If you are not looking for a technical job, get the key: it takes a minute at developer.adzuna.com/signup and there is no card.

export ADZUNA_APP_ID=your_app_id
export ADZUNA_APP_KEY=your_app_key

Or put them in your MCP client's env block alongside JOBSEARCH_HOME. jobsearch-mcp --check reports whether they were picked up.

A note on job boards

Bundled portals use official APIs. That keeps results stable, since an API does not break when a site changes its markup, and it keeps the project within what those services allow.

Requests are throttled to one every few seconds regardless. The throttle is deliberate; please do not remove it.

/add-portal checks a site's robots.txt and terms when you add your own, and prefers an official API where one exists.

Contributing

Issues and pull requests are welcome, and so are questions.

Good first contributions: a job board for your market, a CV template for your country's conventions, or a phrasing fix to the remote-work detection in portals.py (a posting wrongly marked onsite silently costs someone a job, so these are worth more than they look).

Two ground rules: never commit personal data, and keep examples field-neutral so the project stays useful whatever someone does for a living. See also the Code of Conduct.

Support

This is free and always will be.

If it saved you an evening of CV formatting, you can buy me a coffee. Entirely optional, and it buys no priority: bugs and PRs are handled on merit. Starring the repo or filing a good bug report helps the project more.

Licence

MIT for this project's own code and documentation. See LICENSE.

The bundled fonts under cover_letters/OpenFonts/ are not MIT. Lato and Raleway are licensed under the SIL Open Font License 1.1. If you redistribute this project, their OFL.txt files must ship with them. Details in THIRD-PARTY-NOTICES.md.

Built on the ai-job-search framework by Mads Lorentzen. The MCP server, configuration layer and hosting options were added by Trey Morgan.