cv-mirror-mcp

Model Context Protocol server that lints a CV against 5 real ATS parsers.

What it does

Exposes three MCP tools so any MCP-compatible AI agent (Claude Code, Cursor, Windsurf, Zed, OpenCode, Cline, etc.) can analyse a CV against the documented quirks of:

• Workday
• Greenhouse
• Lever
• Taleo (Oracle)
• iCIMS

These are the 5 most-used enterprise ATS systems. Each one parses CVs slightly differently. A "0–100 ATS score" averages those differences into noise. This server surfaces what each one actually does — column handling, emoji stripping, header-footer dropping, date-format quirks — as concrete lint findings with concrete fixes.

The lint rules are derived from public vendor documentation. See docs/vendor-sources.md for citations.

Tools

Install

npm (recommended)

npm install -g cv-mirror-mcp

MCP client config

Add to your MCP client's config file:

Claude Code (~/.claude/mcp.json or .claude.json in project):

{
  "mcpServers": {
    "cv-mirror": {
      "command": "npx",
      "args": ["-y", "cv-mirror-mcp"]
    }
  }
}

Cursor / Windsurf / Zed / Cline: same config format (paste into wherever your client reads mcpServers).

Restart the client. The three tools above auto-register.

Usage

Once installed, just ask your agent:

Scan my CV at ~/Documents/resume.pdf and tell me what each ATS would do to it.

The agent calls analyze_cv, the lint engine runs locally (no network, no upload), and the agent surfaces the structured output:

CV Mirror — multi-vendor ATS lint report
Source: /Users/jane/Documents/resume.pdf
Format: pdf
Pages: 2
Words: 542

[ERROR] Workday
  - ERROR WORKDAY_MULTI_COLUMN: 35% of lines look multi-column. Workday's parser
    reads left-to-right and interleaves both columns into one stream.
    Fix: Convert to single-column layout. Move sidebars (Skills, Tools, Languages)
    above or below the main content.

[OK] Greenhouse
  No issues detected by the simulated parser.

[WARN] Lever
  - WARN LEVER_HEADER_FOOTER: Header/footer-like text detected ("Page 1 of 2").
    Lever historically drops content placed in PDF headers/footers.
    Fix: Remove headers and footers. Page numbers are not needed on a CV.
...

What the lint actually checks

These are real heuristics derived from public ATS docs and vendor support articles. The full list with citations lives in docs/vendor-sources.md.

Requirements

• Node.js >= 18
• An MCP-compatible client (Claude Code, Cursor, Windsurf, Zed, Cline, etc.)

Privacy

The server runs locally inside your agent's process. No upload endpoint. No telemetry. Your CV bytes never leave your machine.

The visual web companion at cv-mirror-web.vercel.app is also fully client-side — same engine, runs in the browser.

Tests

git clone https://github.com/goofypluto999/cv-mirror-mcp.git
cd cv-mirror-mcp
npm install
npm test

19 unit tests covering signal extraction and per-vendor rule firing.

How to use with Claude (and other AI agents)

cv-mirror-mcp exposes its three tools to any MCP-compatible agent. The most common workflow:

1. Install the server: npm install -g cv-mirror-mcp
2. Add it to your MCP client config (Claude Desktop, Cursor, Windsurf, Zed — see Install above).
3. In your agent session, ask: "Run cv-mirror on my CV at /path/to/cv.pdf and tell me what Workday and Greenhouse will get wrong."
4. The agent calls analyze_cv, gets per-vendor lint findings with severity + concrete fixes, and surfaces them.

Once you have a clean CV, you typically need the rest of the application prep — company research, tailored cover letter, fit score, mock interview. Vantage is the paid tool that handles that flow (same team, £5 starter pack, 10 free tokens at signup, no card required for the trial).

The recommended end-to-end flow:

1. Run cv-mirror-mcp via your agent → fix any parse issues your CV has.
2. Run Vantage on the same CV plus a specific job URL → get the full prep pack in ~90 seconds.

Sister projects

• CV Mirror (web) — visual side-by-side parser view. Same lint engine as this MCP server. Drag-drop a PDF, see the reading-order overlay on the actual document. Free, no signup, fully client-side.
• Vantage — once your CV passes the parsers, the next problem is the actual application: company intelligence, tailored cover letter (4 tones), AI-graded mock interview, CV-vs-role fit score, 5-minute pitch outline. Vantage handles that flow in ~90 seconds per application. £5 starter / 20 tokens (never expire), 10 free tokens at signup. Built by the same team.

Contributing

Pull requests welcome. Particularly interested in:

• More vendor simulators (BambooHR, SmartRecruiters, JazzHR, Recruitee, etc.)
• Updated rules when vendors change their parsing behaviour (open an issue with the source link)
• Translations of the lint output

License

MIT. Workday, Greenhouse, Lever, Taleo, and iCIMS are trademarks of their respective owners. This project is not affiliated with any of them; the names are used for descriptive reference (nominative fair use).

Built by Vantage Labs.