Resume-to-Role

All-resume job discovery. Per-job tailoring. Batch applications.

Search for roles using your chosen titles and countries. Rank each job against skills across every resume you import. Generate a job-specific, ATS-friendly resume and cover letter—then fill and submit applications in requested batches of up to five through your signed-in AI host.

Get started · How it works · Job sources · Batch applications · Privacy

Resume-to-Role is a local-first MCP server + portable AI Skill that turns your complete resume library into a focused job-search and application workflow. It searches for your target titles in your selected countries, ranks job descriptions by skill coverage across all imported resumes, and helps your signed-in AI create tailored application documents and send requested batches of up to five applications.

Bring every resume. Find the right roles. Tailor every application. Your chosen titles drive discovery; all your resume evidence powers the ranking and job-specific writing.

How it works

Related MCP server: Shortlist MCP Server

What Resume-to-Role does for you

Search beyond one job board

Use built-in public job feeds and Bing's public search feed, then expand discovery with Google or Bing web search in your signed-in host. Paginated queries search for your chosen job titles across job boards, regional sites, and employer career pages. When a public careers page reveals a board identifier, Resume-to-Role can query supported Greenhouse, Lever, Ashby, and SmartRecruiters boards directly.

Match skills across your full experience

Import your full set of resumes and assess each job's identifiable skills against the combined evidence. A job title does not erase relevant skills from another part of your background: skill coverage and role-title relevance remain separate. The connected AI host makes a semantic assessment; Resume-to-Role verifies cited quotes against the original resume evidence. Jobs matching your target titles remain discoverable even when one resume does not show every required skill.

Tailor each application to the selected job

For a job you select, the Skill guides your host to prioritize that exact job description and the strongest relevant evidence across all your resumes. It builds the resume header, summary, skills, experience, and projects for that role, then writes a separate cover letter for the employer. The result is an ATS-readable resume and a persuasive, role-specific letter—not one generic resume or a summary pasted into a cover letter. Drafts are checked for document structure, evidence provenance, and unsupported numeric claims before export.

The cover-letter workflow targets 220–320 words and asks for a specific opening, a concise evidence-backed example, a reasoned connection to the employer's stated needs, and a natural close. These checks improve consistency; they do not guarantee an employer response or a score from any third-party ATS.

Keep the search aligned to your criteria

• Set the target job titles and countries in your local profile.

• Optionally select remote, hybrid, in-person, or other work arrangements.

• Optionally select relocation support or visa sponsorship.

• Selected arrangement and mobility options are acceptable alternatives: a listing that satisfies any selected option can qualify. Empty lists mean search across all options.

• Country/work authorization remains unknown unless the listing provides evidence. The tool does not treat “remote” as automatic work eligibility.

Send applications in batches

Ask your AI host to apply to a batch of up to five distinct jobs. When browser controls are available, the Skill generates each job's tailored resume and cover letter, fills the employer's form with your saved profile details, and submits the application. It reports an application as sent only after the employer site shows confirmation. If browser controls are unavailable—or a site requires a human step—it prepares the documents and direct links so you can finish the application. Every batch is requested by you; the tool does not run unattended.

Job discovery

Resume-to-Role combines several discovery paths. Availability and freshness depend on the public source and its rate limits.

Search-query coverage includes LinkedIn job pages, Indeed, Glassdoor, Wellfound, Y Combinator Jobs, EURES, Welcome to the Jungle, Working Nomads, Jobgether, Himalayas, Arbeitnow, Jobicy, Landing.jobs, Relocate.me, No Fluff Jobs, StepStone, Kariyer, Techcareer, InfoJobs, Tecnoempleo, Ergodotisi, Work in Finland, Work in Denmark, and employer career pages. LinkedIn is not scraped. Google/Bing web-search queries require native web search in the connected host; the built-in Bing RSS search is a separate source.

The product reports source errors instead of implying an unavailable source was searched. Results retain their reported source and original listing URL; a search-result or careers page is labeled as such when it is not a direct application form.

Works with your signed-in AI

The MCP server provides local data, search, matching, validation, and export tools. It does not call an OpenAI, Anthropic, Google, or Qwen model API. Codex, Claude Code, Gemini CLI, or Qwen Code uses its existing signed-in model for semantic job analysis and writing. No separate LLM API key is needed.

The included career-compass Skill explains how the host should use the MCP tools, search with native web search when available, preserve evidence citations, draft in the selected language, and complete requested application batches. The server command and Skill registration retain the career-compass identifier for compatibility with existing host configurations. Host commands and configuration formats can change; follow the current documentation for your installed host if a CLI command differs.

Multilingual by design

Resume-to-Role supports English, Farsi, Spanish, and Arabic for interaction and generated documents. The Skill can ask the host to translate search titles into the selected search languages. Generated Farsi and Arabic documents use right-to-left layout; PDF export also needs an Arabic-capable font on the computer (Arial, Tahoma, or Noto Sans Arabic).

Get started

Requirements

• Python 3.11 or newer

• uv

• One supported host: Codex, Claude Code, Gemini CLI, or Qwen Code

• Network access for dependency installation and public job-source requests

Windows: one-command setup

Download or clone this repository, open PowerShell in its folder, and run the setup helper for the host you use:

git clone https://github.com/plilian/resume-to-role-mcp.git
cd resume-to-role-mcp
Set-ExecutionPolicy -Scope Process Bypass
.\Setup.ps1 -HostName Codex

Replace Codex with Claude, Gemini, or Qwen as appropriate. The helper installs dependencies, copies the Skill to that host's user Skill folder, and registers the MCP server. It only edits the host you name. If a Gemini or Qwen server entry already exists, setup stops unless -Force is supplied; an existing settings file is backed up before replacement.

To install only the Skill or register only the MCP server, use Install-Skill.ps1 or Register-MCP.ps1. See Host setup details for manual and non-Windows configuration.

macOS and Linux

git clone https://github.com/plilian/resume-to-role-mcp.git
cd resume-to-role-mcp
uv sync

Register the server with your host using uv --directory "/absolute/path/to/resume-to-role-mcp" run career-compass-mcp, and copy skills/career-compass into that host's user Skill directory. Exact configuration steps are in Host setup details.

First search

1. Use profile_update to save your target titles and allowed countries. Work arrangement and mobility filters are optional.

2. Add only the resume folders you want to use to resume_roots, then import them with resume_import. Supported files: PDF, DOCX, TXT, and Markdown.

3. Optionally add your public portfolio or GitHub pages and run evidence_scan_websites. Website facts start as matching-only evidence until you approve their accuracy and visibility.

4. Call discover_jobs for built-in sources. Use the Skill's source_search_queries workflow for host-native Google/Bing search and company_board_search for public ATS listings.

5. Review the paginated results with job_list. Select a job and ask your host to tailor a resume and cover letter for it.

profile.template.json documents the local profile fields. It is an empty template and contains no personal profile data.

MCP tools

All list and search tools that can return long results use pagination. The initial deterministic skill estimate is a screening aid; the host can refine it using exact quotes from all imported resumes. ATS estimates are heuristics based on job keywords and document structure, not a score from a commercial ATS.

Privacy first by design

• Resume contents, profile data, saved jobs, and generated documents are stored in local SQLite under your operating-system user-data directory. Set CAREER_COMPASS_HOME to choose another local directory.

• The MCP server does not upload resumes to its author or a hosted Resume-to-Role service. Resume imports are limited to the folders you explicitly configure.

• The signed-in AI host receives evidence when it is included in a conversation or document request; that processing is governed by the host provider's terms and settings.

• Public job and website sources receive ordinary requests to fetch or search their pages. A host's native web search follows that host's own service and privacy terms.

• Do not add resumes, filled profile data, generated application documents, local databases, secrets, or personal screenshots to this repository.

Project structure

src/career_compass_mcp/    MCP server, discovery, matching, evidence, storage, and exports
skills/career-compass/    Portable host instructions for job search and tailored writing
tests/                    Unit, server-protocol, document, and Skill packaging tests
docs/                     Setup guide and product workflow illustrations
profile.template.json     Empty example profile schema
Setup.ps1                 Windows setup for one supported host

Development

uv sync --group dev
uv run pytest

The tests cover the MCP handshake, matching and evidence checks, source/query logic, language handling, document export, and Skill packaging.

License

Resume-to-Role is released under the MIT License.

Resume-to-Role — your whole resume library, matched to real openings and tailored for every application.