resume-mcp-server

resume-mcp-server is an MCP (Model Context Protocol) server designed to provide Claude or other MCP clients with structured, searchable access to a local collection of resume files. Job seekers often accumulate a large number of documents: multiple resume versions tailored to different positions, cover letter drafts, reference information, and more, making manual search and use very cumbersome. After pointing the server at a resume folder, the AI can directly answer questions such as "Which of my resumes highlights Kubernetes experience?", "What achievements did I list for backend roles?", or "Draft a cover letter based on my work at Acme Corp", without the need to manually paste content.

Main capabilities:

• Multi-format parsing: parses .docx, .pdf, .md, and .txt documents into structured data, including contact information, work experience, education background, skills, and side projects.
• Automatic deduplication: matches multiple resumes belonging to the same person by email or name (such as the .docx and .pdf versions of the same resume), merging them into the most informative copy to avoid duplicate entries interfering with search and analysis results.
• Automatic hot reload: a file system watcher immediately reindexes when documents change, with no need to restart the server.
• Document type inference: automatically classifies documents as resume, cover_letter, application_material, or other based on filename patterns, with per-category overrides available via environment variables.
• Full-text and structured search: use search_resumes to search entire documents, or filter any entity type (skills, work experience, achievements, side projects, education) through scoped query, technology, or competency parameters.
• Three search modes: and, or, and regex matching, consistently available across all tools that accept query-like parameters.
• Unified pagination: all list-style tools return the same total_count / items / has_more / next_offset / message wrapper, with limit / offset validated and capped at 200 entries.
• Unified error shape: all failures return {"error": "..."}, so callers only need to check one shape.
• Collection analysis: get_collection_stats and get_skill_frequency provide aggregate counts and cross-resume skill frequency.
• ATS-style job match ranking: list_ranked_resumes scores each resume against a pasted job description (fuzzy skill matching plus keyword coverage) and sorts them by best match first; match strictness and score weights can be adjusted per call.
• Read-only and safe: all tools are marked readOnlyHint / idempotentHint / openWorldHint: false, and will not modify files or access anything outside the local document collection.
• Flexible deployment: supports running via stdio or HTTP, can run standalone or be deployed via Docker/Docker Compose, supports CORS, and is configured through environment variables or a .env file.

How to use: Commands for a quick try (using the built-in sample resume) and for connecting to Claude Code are given in the materials. Docker deployment (recommended):

1. Set the resume directory: copy the sample environment file and set the document path.
2. Optional: sync the image version, tagging the image with the current pyproject.toml version.
3. Build and start, and the server will be at http://localhost:8001/mcp Available.
4. Connect an AI client, such as Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS), VS Code (.vscode/mcp.json), or add it globally to ~/.claude.json. You can also run the image directly, without Compose, for MCP clients that use stdio transport (including Glama.ai and Claude Desktop). Development environment: To run the server locally or without Docker, you can create a .env file and then run resume-mcp-server; .env will be loaded automatically. Shell environment variables or variables set by the MCP client always take precedence over .env. Connecting an AI client (stdio): In the Claude Desktop configuration, if resume-mcp-server is not in PATH, use the full path (for example ~/.venv/bin/resume-mcp-server).

Configuration:

• Each DOC_TYPE_PATTERN_* variable replaces the default regex for that category (filenames are matched in order: resume, cover letter, application material, and the rest are classified as other). If unset, the default is kept; invalid regexes are ignored and the default is used.
• On startup, the server recursively scans RESUME_DIR and automatically reloads when files change.
• Document type inference is based on filename, and the three regexes can be overridden via DOC_TYPE_PATTERN_RESUME, DOC_TYPE_PATTERN_COVER_LETTER, and DOC_TYPE_PATTERN_APPLICATION_MATERIAL.

Search behavior:

• Most tools that accept a query (or technology / competency) parameter split by whitespace and support the and, or, and regex matching modes via the optional mode parameter.
• Multi-field note: for tools that search multiple fields (company name, job title, achievement text, etc.), AND mode requires all words to appear in the same field, not across fields. When looser cross-field matching is needed, use OR mode. Regex mode also matches by field.
• Single-word queries behave the same in and / or mode.
• search_resumes_by_skill accepts a single skill string or a list of skills. For a list, mode also serves as a control: require the resume to match every skill in the list ("and") or any skill ("or"); "regex" mode combines multiple skills with OR semantics.
• An empty query or empty skill list returns {"error": "..."} instead of an empty result, to distinguish a call error from a legitimate zero-match search.
• All list_* tools (as well as search_resumes / search_resumes_by_skill) accept limit and offset parameters and return a consistent wrapper: total_count is the full number of matches before slicing; has_more and next_offset directly indicate whether to continue paging; message restates this in natural language. When there are no more, has_more is false, next_offset is null, and message is "All N results shown.".
• limit must be greater than 0, and offset must be 0 or greater, otherwise {"error": "..."} is returned. An offset beyond the total number of results is not an error, but a valid "past the end" page (items: [], has_more: false).
• Caps and defaults: limit is silently capped at 200 no matter how much is requested; if more is requested, the response is still returned (not an error), but message is prefixed with "Requested limit N capped to 200.". The default limit varies by tool and is usually lower for heavier, deeply nested responses.

Error handling:

• Each tool returns a dictionary. On failure, the dictionary is exactly {"error": "<message>"}, which is the only failure shape in the API, so callers only need to check the "error" key. Coverage: ID not found, resume_id filter matching no resumes, invalid regex pattern, invalid limit / offset values. The resume_id filter matches a resume but there are zero child records (for example list_work_experiences(resume_id=<valid>) for people with no work history) is not an error; it returns an empty items list.
• The success shape of get_resume is {"text": "..."}, so both success and failure are dictionaries and can be distinguished by key.

Tools: A total of 20 tools are exposed, covering full-text search, skill lookup, company and role queries, achievement mining, education search, ATS-style job matching ranking, collection analysis, and more. Each tool is read-only (readOnlyHint: true) and does not modify state or access anything outside the local document collection (openWorldHint: false). See docs/TOOLS.md for the complete parameter table and return shapes.

Use cases:

• Job seekers managing multiple resume versions and cover letters, quickly finding specific skills or achievements.
• Automatically ranking resumes based on a job description.
• Analyzing skill frequency and collection statistics.
• Citing specific work experience when drafting a cover letter.

Limitations:

• Only .docx, .pdf, .md, and .txt formats are supported.
• Requires an MCP client (such as Claude) to connect and use.
• Other limitations not mentioned in the materials are not currently provided.