# MatchCV MCP Server

[![npm](https://img.shields.io/npm/v/matchcv-mcp)](https://www.npmjs.com/package/matchcv-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)

Resume tools for MCP clients. Check a resume against ATS rules, parse a job description into structured
requirements, get rewrite-level suggestions, and generate a fully tailored resume with a shareable preview
link — all from inside Claude, Cursor, Codex, or any other MCP-compatible client.

Powered by [MatchCV](https://matchcv.co) · [MCP docs](https://matchcv.co/docs/mcp) · [Get started free](https://matchcv.co/login)

---

## Tools

| Tool | What it does |
|---|---|
| `ats_check` | Scores resume text 0–100 for ATS compatibility, with a recruiter take, prioritized issues and fixes, and detected strengths |
| `analyze_job_description` | Turns a job posting into structured JSON: title, company, seniority, industry, must-have / nice-to-have keywords, responsibilities |
| `optimize_resume` | Prioritized improvement suggestions with example rewrites, optionally targeted at a role, a JD, and specific missing keywords |
| `roast_resume` | Blunt recruiter-style critique plus an ATS score, returned as a public shareable report link |
| `extract_resume_text` | Reads a local PDF/DOC/DOCX/TXT resume and returns plain text, optionally AI-parsed into structured JSON |
| `tailor_resume` | Full pipeline — analyze the JD, rewrite the resume for that role, return the tailored JSON plus a preview page you can open and download as PDF |

## Install

Requires Node.js 20+. No API key and no account are needed to start.

### Claude Desktop / Claude Code

Add to your MCP config (`claude_desktop_config.json`, or run `claude mcp add`):

```json
{
  "mcpServers": {
    "matchcv": {
      "command": "npx",
      "args": ["-y", "matchcv-mcp"]
    }
  }
}
```

### Cursor

`~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project):

```json
{
  "mcpServers": {
    "matchcv": {
      "command": "npx",
      "args": ["-y", "matchcv-mcp"]
    }
  }
}
```

### Codex CLI

`~/.codex/config.toml`:

```toml
[mcp_servers.matchcv]
command = "npx"
args = ["-y", "matchcv-mcp"]
```

### Any other MCP client

The server speaks MCP over stdio. Run it directly with:

```bash
npx -y matchcv-mcp
```

## Example prompts

- *"Read `~/Documents/resume.pdf` and tell me how it scores against ATS."*
- *"Here's a job posting — what keywords is my resume missing?"*
- *"Roast my resume, I want the honest version."*
- *"Tailor my resume to this job description and give me the preview link."*

## Usage limits

The tools call MatchCV's public endpoints, so free usage is capped per day, per IP address:

| | Free (no account) | Signed in | Pro |
|---|---:|---:|---:|
| `ats_check`, `analyze_job_description`, `optimize_resume`, `roast_resume`, structured parsing | 3/day | 10/day | Unlimited |
| `tailor_resume` | 1/day | 3/day | Unlimited |

Plain text extraction (`extract_resume_text` without `structured: true`) is unlimited — it runs no AI.

Quota errors come back as a readable message telling you how to raise the limit. See
[matchcv.co/pricing](https://matchcv.co/pricing).

## Configuration

| Environment variable | Default | Purpose |
|---|---|---|
| `MATCHCV_BASE_URL` | `https://matchcv.co` | API origin. Only needed to point at a development deployment. |

## Privacy

This server holds no credentials and stores nothing locally. Resume and job description text is sent to the
MatchCV API over HTTPS for processing. `roast_resume` and `tailor_resume` create a page at an unguessable
public URL so you can open and share the result; the other tools store nothing. See the
[privacy policy](https://matchcv.co/privacy).

## Development

```bash
npm install
npm run build
node dist/index.js
```

Point it at a local MatchCV instance with `MATCHCV_BASE_URL=http://localhost:3000`.

## License

MIT — see [LICENSE](./LICENSE).