resume-mcp-server
The resume-mcp-server provides structured access to a collection of job application documents (resumes, cover letters, application materials) with tools for browsing, searching, and extracting detailed information.
Document Browsing
List all documents, optionally filtered by type (
resume,cover_letter,application_material,other)List lightweight resume summaries (ID, name, email, phone) for token-efficient orientation
Retrieve the full extracted text of any document by path
Get a resume's structured profile (contact info, professional statement, education) without nested data
Searching
Full-text search across all documents by keyword or phrase, with optional type filtering
Search resumes by person name (partial match supported)
Search resumes by badge skill (e.g., find everyone who lists "Python")
Search badge skills/technologies by title keyword
Work Experience & Achievements
List and retrieve individual work experience entries, optionally filtered by resume or current roles
Search work experiences by company name, position title, or achievement content
List, retrieve, and directly search achievement bullets for token-efficient matching
Skills & Projects
List and retrieve badge skills (technologies, tools, languages), optionally scoped to one resume
Search side projects by name, description, or associated technologies
Education
Search education entries by institution, degree, or competencies
The server supports common document formats (.docx, .pdf, .md, .txt), auto-parses files on startup with hot-reload on changes, and integrates with AI clients like Claude Desktop, Claude Code, and VS Code via HTTP or stdio transport.
resume-mcp-server
An MCP server that gives Claude (or any MCP client) structured, searchable access to your resume collection — resumes, cover letters, and application materials in .docx, .pdf, .md, or .txt format.
Job seekers accumulate document sprawl fast: multiple resume versions tailored to different roles, cover letter drafts, reference sheets. Manually digging through them to draft a new application is tedious. Point this server at your resume folder and Claude can answer questions like "which of my resumes highlights Kubernetes experience?", "what achievements have I listed across my backend roles?", or "draft a cover letter drawing from my work at Acme Corp" — without you pasting anything.
The server parses each document into structured data (contact info, work history, education, skills, side projects) and exposes 20 tools covering full-text search, skill lookup, company and role queries, achievement mining, education search, ATS-style job-match ranking, collection analytics, and more. Files are watched and re-indexed automatically, so edits to your documents are reflected immediately.
Features
Multi-format parsing —
.docx,.pdf,.md, and.txtdocuments are parsed into structured data: contact info, work history, education, skills, and side projects.Automatic de-duplication — resumes for the same person across multiple files (e.g. a
.docxand a.pdfof the same resume) are matched by email or name and collapsed to the richest copy, so search and analytics aren't skewed by duplicates.Automatic hot-reload — a filesystem watcher re-indexes your documents as soon as they change, no server restart needed.
Document type inference — files are automatically classified as
resume,cover_letter,application_material, orotherbased on filename patterns, which can be overridden per category via environment variables.Full-text and structured search — search whole documents with
search_resumes, or filter any entity type (skills, work experience, achievements, side projects, education) with a scopedquery,technology, orcompetencyparameter.Three search modes —
and,or, andregexmatching, available consistently on every tool that accepts a query-like parameter.Uniform pagination — every list-style tool returns the same
total_count/items/has_more/next_offset/messageenvelope, with validatedlimit/offsetand a 200-item cap.Unified error shape — every failure returns
{"error": "..."}, so callers only need to check for one shape regardless of which tool they called.Collection analytics —
get_collection_statsandget_skill_frequencysurface aggregate counts and cross-resume skill popularity.ATS-style job-match ranking —
list_ranked_resumesscores every resume against a pasted job description (fuzzy skill matching plus keyword coverage) and ranks them best-match-first; match strictness and score weighting are tunable per call.Read-only and safe by construction — every tool is annotated
readOnlyHint/idempotentHint/openWorldHint: false; nothing mutates your files or reaches outside the local document collection.Flexible deployment — run over stdio or HTTP, standalone or via Docker/Docker Compose with CORS support, configured through environment variables or a
.envfile.
See MCP Tools below for the full list of tools this exposes. For best extraction quality, see the Resume Formatting Guide.
Related MCP server: Resume Forge MCP
Quick Start
Give Claude structured access to your resume collection. The server parses your documents on startup and exposes 20 tools for searching by name, company, skill, education, side project, or full text, ranking resumes against a job description, plus analytics tools for skill frequency and collection statistics — with automatic hot-reload when files change.
Try it immediately with the included sample resumes:
pip install resume-mcp-server
RESUME_DIR=./sample_resumes resume-mcp-serverThen connect Claude Code:
claude mcp add resume-mcp-server resume-mcp-server -e RESUME_DIR=$(pwd)/sample_resumesFor a persistent setup with Docker or your own documents, see Docker Deploy or Dev Environment.
Docker Deploy
The recommended way to run the server. Docker Compose exposes the server over HTTP so any AI client can connect to it.
1. Set your resume directory
Copy the example env file and set your documents path:
cp .env.example .env
# then edit RESUME_DIR_HOST in .env2. Sync the image version (optional)
Stamp the image with the current pyproject.toml version:
python scripts/sync_version.py3. Build and start
docker compose build resume-mcp
docker compose up -dThe server is now available at http://localhost:8001/mcp.
4. Connect your AI client
Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
{
"mcpServers": {
"resume-mcp-server": {
"type": "http",
"url": "http://localhost:8001/mcp"
}
}
}VS Code (.vscode/mcp.json):
{
"servers": {
"resume-mcp-server": {
"type": "http",
"url": "http://localhost:8001/mcp"
}
}
}Claude Code:
claude mcp add resume-mcp-server --transport http http://localhost:8001/mcpTo add it globally across all projects, add the following to ~/.claude.json instead:
{
"mcpServers": {
"resume-mcp-server": {
"type": "http",
"url": "http://localhost:8001/mcp"
}
}
}Stopping
docker compose downDocker (stdio)
Run the image directly — no Compose needed — for MCP clients that use stdio transport (including Glama.ai and Claude Desktop):
docker run -i --rm -v /path/to/your/resumes:/resumes resume-mcp-serverClaude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
{
"mcpServers": {
"resume-mcp-server": {
"command": "docker",
"args": ["run", "-i", "--rm", "-v", "/path/to/your/resumes:/resumes", "resume-mcp-server"]
}
}
}Dev Environment
For local development or running the server without Docker.
Prerequisites
Python 3.12+
Install
pip install .
# include test dependencies:
pip install ".[dev]"Run
resume-mcp-server
# with a custom directory:
RESUME_DIR=/path/to/docs resume-mcp-serverOr create a .env file in the directory you run the server from:
# .env
RESUME_DIR=/path/to/docs
FASTMCP_PORT=8001Then just run resume-mcp-server — the .env is loaded automatically. Variables already set in your shell or by the MCP client always take precedence over .env values.
Connect your AI client (stdio)
Claude Desktop:
{
"mcpServers": {
"resume-mcp-server": {
"command": "resume-mcp-server",
"env": {
"RESUME_DIR": "/path/to/your/resumes"
}
}
}
}If resume-mcp-server is not on your PATH, use the full path (e.g. ~/.venv/bin/resume-mcp-server).
Claude Code:
claude mcp add resume-mcp-server resume-mcp-server -e RESUME_DIR=/path/to/your/resumesuvx:
{
"mcpServers": {
"resume-mcp-server": {
"command": "uvx",
"args": ["resume-mcp-server"],
"env": {
"RESUME_DIR": "/path/to/your/resumes"
}
}
}
}Configuration
Docker Compose (.env):
Variable | Description |
| Path on your machine to the documents directory — mounted to |
| Port the HTTP server listens on (default |
| Logging verbosity: |
Local run (environment variables or .env):
Variable | Default | Description |
|
| Directory scanned for documents |
|
| Transport protocol ( |
|
| Bind address |
|
| Port the HTTP server listens on |
|
| Regex used to classify a filename as |
|
| Regex used to classify a filename as |
|
| Regex used to classify a filename as |
A .env file in the working directory is loaded automatically on startup if present. Shell environment variables and values set by the MCP client always take precedence over .env values.
Each DOC_TYPE_PATTERN_* variable replaces the default regex for that category (filenames are matched in order: resume, then cover letter, then application material, then everything else falls back to other). Leave a variable unset to keep its default; an invalid regex is ignored and the default is used instead.
The server scans RESUME_DIR recursively on startup and reloads automatically when files change.
Document type inference
Types are inferred from filenames:
Type | Filename patterns |
| contains |
|
|
|
|
| everything else |
Each of the three regexes can be overridden with DOC_TYPE_PATTERN_RESUME, DOC_TYPE_PATTERN_COVER_LETTER, and DOC_TYPE_PATTERN_APPLICATION_MATERIAL — see Configuration.
Search behavior
Most tools that accept a query (or technology/competency) parameter split it on whitespace and support three match modes via the optional mode parameter:
| Behavior |
| All tokens must appear within the same field. |
| Any token is sufficient. |
| The query is compiled as-is (not tokenized or escaped) into a case-insensitive regular expression and matched against the field. Use this for grep-style power — alternation, wildcards, anchors, etc., e.g. |
Multi-field note: For tools that search several fields (company name, position title, achievement text, etc.), AND mode requires all tokens to co-occur in the same field, not spread across fields. Use OR mode when you want a looser cross-field match. Regex mode also matches per-field.
Single-word queries behave identically in and/or mode.
Every tool that accepts a query-like parameter — including search_resumes, the whole-document keyword search — shares this same "and"/"or"/"regex" vocabulary.
search_resumes_by_skill accepts either a single skill string or a list of skills. For a list, mode does double duty: it also controls whether a resume must match EACH skill in the list ("and") or ANY skill ("or"); "regex" mode combines multiple skills with OR semantics.
An empty query or an empty skill list returns {"error": "..."} rather than an empty result — this distinguishes a caller mistake from a legitimate zero-match search.
Pagination
All list_* tools (and search_resumes/search_resumes_by_skill) accept limit and offset parameters and return a consistent envelope:
{
"total_count": 247,
"items": [...],
"has_more": true,
"next_offset": 100,
"message": "100 of 247 results shown. Call again with offset=100 to see more."
}total_count is the full match count before slicing. has_more and next_offset tell you directly whether to page further — no need to compute offset + len(items) < total_count yourself — and message restates that in plain language, ready to act on. When there's nothing left, has_more is false, next_offset is null, and message reads "All N results shown.".
limit must be greater than 0 and offset must be 0 or greater — otherwise the tool returns {"error": "..."}. An offset beyond the total result count is not an error; it's a valid "past the end" page (items: [], has_more: false).
Cap and defaults. limit is silently capped at 200 regardless of what's requested — if you ask for more, the response still comes back (not an error), but message is prefixed with "Requested limit N capped to 200." so you know it happened. Default limit varies by tool, generally lower for heavier, deeply-nested responses:
Tool | Default |
| 10 (each item is a fully nested resume) |
| 25 |
| 50 |
| 100 |
| 20 (not part of the pagination envelope, but shares the same 200 cap) |
Error handling
Every tool returns a dict. On failure, the dict is exactly {"error": "<message>"} — this is the only failure shape in the API, so a caller can check for the "error" key regardless of which tool it called. This covers: not-found IDs, a resume_id filter that doesn't match any resume, invalid regex patterns, and invalid limit/offset values. A resume_id filter that does match a resume but simply has zero matching child records (e.g. list_work_experiences(resume_id=<valid>) for someone with no work history) is not an error — it returns an empty items list.
get_resume's success shape is {"text": "..."} so that success and failure are both dicts, distinguishable by key.
MCP Tools
20 tools are exposed, covering full-text search, skill lookup, company and role queries, achievement mining, education search, ATS-style job-match ranking, collection analytics, and more. Every tool is read-only (readOnlyHint: true) — none mutate state or reach outside the local document collection (openWorldHint: false).
Tool | Description |
| Lightweight identity records (id, name, email, phone) for orienting before fetching details; optional |
| A resume's top-level fields (contact info, statement, education) without nested lists |
| A resume's complete nested structure (work experiences, skills, side projects, education) in one call |
| List all documents, optionally filtered by type |
| Full extracted text of a document, keyed by path (not resume_id) |
| Full-text search across all documents, sorted by match count |
| List badge skills, optionally scoped to a resume and/or filtered by title |
| A single badge skill by ID |
| Find which resumes list one or more given badge skills (accepts a string or a list) |
| Badge skills ranked by how many resumes list them |
| Rank every resume against a pasted job description (fuzzy skill match + keyword coverage) |
| List work experiences, optionally scoped to a resume, current-only, and/or a keyword query |
| A single work experience entry with its achievement bullets |
| List achievement bullets, optionally scoped to a resume and/or a keyword query |
| A single achievement bullet by ID |
| List side projects, optionally scoped to a resume and/or matched by keyword or technology |
| A single side project by ID, including demonstrated technologies |
| List education entries, optionally scoped to a resume and/or matched by keyword or competency |
| A single education entry by ID, including its competencies |
| Aggregate counts and averages across the entire loaded collection |
See docs/TOOLS.md for full parameter tables and return shapes for every tool.
Available Tools
19 toolsget_achievementARead-onlyIdempotent
Get a single achievement (phrase skill) by ID. Returns {"error": ...} if id is not found.
Inputs: id (required). Returns: object
get_badge_skillARead-onlyIdempotent
Get a single badge skill by ID. Returns {"error": ...} if id is not found.
Inputs: id (required). Returns: object
get_collection_statsARead-onlyIdempotent
Return aggregate counts and averages across the entire loaded resume collection.
Returns total_resumes, total_work_experiences, total_unique_skills, total_side_projects, total_education_entries, total_achievements, avg_skills_per_resume, avg_work_experiences_per_resume. Example: get_collection_stats()
Inputs: no named parameters. Returns: object
get_educationARead-onlyIdempotent
Get a single education entry by ID, including its competencies. Returns {"error": ...} if id is not found.
Inputs: id (required). Returns: object
get_resumeARead-onlyIdempotent
Return the full extracted text of a document, as {"text": "..."}. Note: takes a file path (see list_resumes), not a resume_id — use get_resume_profile or list_resumes to fetch structured data by resume_id instead. Returns {"error": ...} if path is not found.
Inputs: path (required). Returns: object
get_resume_fullARead-onlyIdempotent
Get a resume's complete nested structure in one call: profile fields plus all work experiences (with achievements), badge skills, side projects (with technologies), and education entries (with competencies). Prefer get_resume_profile plus the scoped list_* tools (list_work_experiences, list_skills, list_side_projects, list_education) when you only need part of this — it's more token-efficient. Use get_resume_full when you need the whole picture at once. Returns {"error": ...} if resume_id is not found.
Inputs: resume_id (required). Returns: object
get_resume_profileARead-onlyIdempotent
Get a resume's top-level fields (contact info, professional statement, education) without the nested work experience and badge skill lists. See also: get_resume_full for everything about this resume in one call. Returns {"error": ...} if resume_id is not found.
Inputs: resume_id (required). Returns: object
get_side_projectARead-onlyIdempotent
Get a single side project by ID, including the technologies it demonstrates. Returns {"error": ...} if id is not found.
Inputs: id (required). Returns: object
get_skill_frequencyARead-onlyIdempotent
Return badge skills ranked by how many resumes list them, in descending order.
Useful for identifying the most common technologies across all candidates.
Inputs: limit. Returns: result
get_work_experienceARead-onlyIdempotent
Get a single work experience entry with its achievements. Returns {"error": ...} if id is not found.
Inputs: id (required). Returns: object
list_achievementsARead-onlyIdempotent
List achievements (resume bullet points), optionally filtered to a specific resume and/or a keyword query matched against the achievement text (absorbs the old search_achievements tool).
Response shape depends on the arguments given, to keep the common case cheap:
resume_id given, query omitted: bare {id, desc} per item (cheapest — you already know which resume these belong to).
query given, and/or resume_id omitted: each item also includes company_name, position_title, work_experience_id, and resume_id, since that context would otherwise be unrecoverable from the achievement alone. Response includes total_count and items for pagination. Returns {"error": ...} if resume_id is given but not found.
Inputs: mode, limit, query, offset, +1 more. Returns: object
list_educationARead-onlyIdempotent
List education entries (degree, institution, year, and relevant coursework/competencies), optionally filtered to a resume and/or matched by keyword or competency (absorbs the old search_education and search_education_by_competency tools).
If competency is given, entries are matched against competency names only, and each result uses a lighter shape: id, institution, degree, year, matched_competencies, resume_id.
Else if query is given, entries are matched against institution, degree, or competency names, and each result includes the full nested structure plus resume_id.
If both are given, competency takes precedence and query is ignored.
If neither is given, today's plain listing behavior applies. Response includes total_count and items for pagination. Returns {"error": ...} if resume_id is given but not found.
Inputs: mode, limit, query, offset, +2 more. Returns: object
list_resumesARead-onlyIdempotent
List all documents. When doc_type is 'resume' (or omitted), structured resume data is returned if available; otherwise flat file metadata is returned. Response includes total_count and items for pagination. See also: list_resume_summaries for a lighter-weight, more token-efficient listing; get_resume_full for one resume's full nested structure by resume_id.
Inputs: limit, offset, doc_type. Returns: object
list_resume_summariesARead-onlyIdempotent
List resumes as lightweight identity records — id, name, email, phone only. Use this to orient and pick a resume_id before fetching details with other tools. Much more token-efficient than list_resumes when you only need to identify who is present. Pass query to filter by first or last name (absorbs the old search_resumes_by_name tool). Response includes total_count and items for pagination.
Inputs: mode, limit, query, offset. Returns: object
list_side_projectsARead-onlyIdempotent
List side projects (personal/portfolio projects, distinct from work experience), optionally filtered to a resume and/or matched by keyword or technology (absorbs the old search_side_projects and search_side_projects_by_technology tools).
If technology is given, projects are matched against technology names only, and each result uses a lighter shape: id, name, description, matched_technologies, resume_id.
Else if query is given, projects are matched against name, description, or technology names, and each result includes the full nested structure plus resume_id.
If both are given, technology takes precedence and query is ignored.
If neither is given, today's plain listing behavior applies. Response includes total_count and items for pagination. Returns {"error": ...} if resume_id is given but not found.
Inputs: mode, limit, query, offset, +2 more. Returns: object
list_skillsARead-onlyIdempotent
List badge skills (technologies, tools, languages), optionally filtered to a resume and/or a keyword query matched against the skill title (absorbs the old search_skills tool). Note: badge skills are deduplicated and shared across resumes by title, so — unlike work experiences, side projects, and education — items here do not carry a resume_id. Response includes total_count and items for pagination. Returns {"error": ...} if resume_id is given but not found.
Inputs: mode, limit, query, offset, +1 more. Returns: object
list_work_experiencesARead-onlyIdempotent
List work experiences, optionally filtered to a specific resume, only current roles, and/or a keyword query matched against company name, position title, or achievement descriptions (absorbs the old search_work_experiences tool). Each result includes a resume_id field identifying which resume the experience belongs to. Response includes total_count and items for pagination. Returns {"error": ...} if resume_id is given but not found.
Inputs: mode, limit, query, offset, +2 more. Returns: object
search_resumesARead-onlyIdempotent
Search across all documents for a keyword or phrase. Response includes total_count, items, has_more, next_offset, and message for pagination.
Inputs: query (required), mode, limit, offset, +1 more. Returns: object
search_resumes_by_skillARead-onlyIdempotent
Find which resumes list one or more given badge skills. Returns resume identity and matched skill names only — more token-efficient than list_resumes when filtering by skill. Accepts either a single skill string or a list of skills to filter by multiple at once.
Each result includes: id, first_name, last_name, matched_skills. Response includes total_count, items, has_more, next_offset, and message for pagination.
Inputs: skill (required), mode, limit, offset. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 19 tools
Every tool targets a distinct entity or level of detail: list_* for collections, get_* for individual items, search_* for cross-cutting queries. Even similar-sounding tools like list_resumes vs list_resume_summaries serve clearly different purposes (full vs lightweight).
All tool names follow a consistent verb_noun pattern in snake_case (e.g., get_resume_profile, list_work_experiences, search_resumes_by_skill). No mixing of conventions or vague verbs.
19 tools is slightly above the typical 3-15 range, but the number is well-justified by the domain's complexity (multiple entity types: resumes, skills, experiences, projects, education) and the need for both list and detail endpoints per entity.
The tool surface provides comprehensive read-only coverage: every entity (resume, work experience, achievement, skill, side project, education) has a list and get endpoint, plus cross-cutting search and aggregate stats. No obvious gaps for retrieval.
Maintenance
Related MCP Connectors
Public MCP server for discovering open jobs. Search, filter, and get application links.
Personal knowledge base MCP server with semantic search, auto-categorization, metadata extraction
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables Claude to intelligently query and analyze your resume using RAG technology. Supports skill matching against job requirements and answering questions about your professional background from locally stored resume files.MIT
- AlicenseAqualityDmaintenanceAn MCP server for intelligent LaTeX resume generation with multiple templates, quality scoring, and job description tailoring.11MIT
- AlicenseNot gradedqualityCmaintenanceAn MCP server that provides a structured API for AI agents to query a person's resume, including profile, projects, writing, and gated access to experience and skills.MIT
- FlicenseAqualityDmaintenanceA local job-hunting MCP server for discovering jobs across pluggable web sources, tracking applications through a status lifecycle, and managing profiles/resumes, with geo/map-region search.12-