# ats-scanner-mcp

A Jobscan-style ATS resume scanner packaged as an [MCP](https://modelcontextprotocol.io) server, so Claude Desktop can scan your resume against a job posting, show the match rate and missing keywords, and then propose edits — no subscription, no API key, nothing leaves your machine.

Claude Desktop is the "brain": the server does the deterministic parts an ATS does (keyword extraction, matching, searchability checks, scoring) and hands Claude structured results plus the raw text so it can reason about semantic gaps and rewrite bullets.

## What it checks

| Area | What the scanner does |
|---|---|
| Hard skills | Matches ~250 dictionary skills (languages, frameworks, cloud, data, DevOps, AI/LLM, security, practices, tools) with alias handling (`Node` = `Node.js` = `NodeJS`), classifies each as **required / preferred / mentioned** by reading the posting's section headings, and counts mentions on both sides. |
| Soft skills | Same, for communication / collaboration / leadership / ownership etc. |
| Job title | Exact title in the resume, core title (`Software Engineer` from `Senior Software Engineer, Applied AI`), or word overlap. |
| Education | Degree / certification requirements vs what the resume shows; softened when the posting says "or equivalent experience". |
| Experience | Minimum years in the posting vs the date range in your Experience section. |
| Searchability | Email, phone, LinkedIn, location, standard section headings, dates, measurable results, weak bullet openers, overlong bullets, length, file name, PDF parsing red flags (unreadable glyphs, multi-column layouts). |
| Discovered phrases | Recurring phrases in the posting that aren't in the dictionary — Claude judges relevance. |

Match rate = hard skills 45% · searchability 20% · title 10% · soft skills 10% · education 10% · experience 5%.

## Install

```bash
git clone https://github.com/<you>/ats-scanner-mcp.git
cd ats-scanner-mcp
npm install
npm run build
```

Requires Node 18+.

## Claude Desktop configuration

Add to `claude_desktop_config.json` (Settings → Developer → Edit Config):

```json
{
  "mcpServers": {
    "ats-scanner": {
      "command": "node",
      "args": ["/absolute/path/to/ats-scanner-mcp/dist/index.js"],
      "env": {
        "ATS_RESUME_DIR": "/home/you/Documents/Resumes"
      }
    }
  }
}
```

Restart Claude Desktop. `ATS_RESUME_DIR` is optional (defaults to `~/Documents/Resumes`); it lets you refer to resumes by bare file name.

Optional: `ATS_EXTRA_SKILLS=/path/to/skills.json` adds your own dictionary entries:

```json
[
  { "name": "Amplify Gen 2", "aliases": ["amplify gen2"], "category": "cloud" },
  { "name": "Proxyware Detection", "category": "security" }
]
```

## Using it in Claude Desktop

Paste a posting and ask:

> Run an ATS scan of `EQ_Maitland-Soto_Resume_2026.pdf` against this posting and suggest edits: …

Or use the built-in **tailor_resume** prompt (the "+" / prompts menu in Claude Desktop), which walks Claude through: scan → report gaps → propose honest before/after edits → re-scan the edited draft with `resume_text` and report the new score.

### Tools

| Tool | Purpose |
|---|---|
| `scan_resume` | Full scan. `resume_path` **or** `resume_text` (to re-score a draft), `job_text`, optional `job_title`, `format` = markdown / json / both. |
| `extract_job_keywords` | Title, company, hard/soft skills with importance + counts, education, years, discovered phrases. |
| `parse_resume` | What an ATS sees: sections, contact info, dates, bullet stats, warnings, extracted text. |
| `list_resumes` | Files in your resume folder. |
| `compare_resumes` | Rank several resume variants against one posting. |

Resumes: PDF, Markdown, or plain text. (DOCX: export to PDF first.)

## CLI (no Claude needed)

```bash
npm run cli -- ~/Documents/Resumes/my-resume.pdf posting.txt          # markdown report
npm run cli -- ~/Documents/Resumes/my-resume.pdf posting.txt --json   # structured
```

Try it with the bundled sample: `npm run cli -- examples/Alex-Sample-Resume.pdf examples/sample-posting.txt`

## Development

```bash
npm test        # vitest
npm run dev     # tsc --watch
```

Layout: `src/skills.ts` (dictionary) · `src/text.ts` (matching) · `src/extract.ts` (posting → profile) · `src/resume.ts` (resume parsing) · `src/score.ts` (scoring + checks) · `src/report.ts` (markdown) · `src/index.ts` (MCP server) · `src/cli.ts`.

## Honest-use note

The scanner tells you which words are missing; it does not know whether you have the skill. The `tailor_resume` prompt instructs Claude to only add skills you can evidence and to say plainly when you don't have something. Keyword stuffing gets past filters and then fails in interviews.

## License

MIT