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 27 tools covering full-text search, skill lookup, company and role queries, achievement mining, education search, collection analytics, and more. Files are watched and re-indexed automatically, so edits to your documents are reflected immediately.

Quick Start

Give Claude structured access to your resume collection. The server parses your documents on startup and exposes 27 tools for searching by name, company, skill, education, side project, or full text, 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-server

Then connect Claude Code:

claude mcp add resume-collection resume-mcp-server -e RESUME_DIR=$(pwd)/sample_resumes

For a persistent setup with Docker or your own documents, see Docker Deploy or Dev Environment.

Related MCP server: NOUZ MCP Server

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 .env

2. Sync the image version (optional)

Stamp the image with the current pyproject.toml version:

python scripts/sync_version.py

3. Build and start

docker compose build resume-mcp
docker compose up -d

The 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-collection": {
      "type": "http",
      "url": "http://localhost:8001/mcp"
    }
  }
}

VS Code (.vscode/mcp.json):

{
  "servers": {
    "resume-collection": {
      "type": "http",
      "url": "http://localhost:8001/mcp"
    }
  }
}

Claude Code:

claude mcp add resume-collection --transport http http://localhost:8001/mcp

To add it globally across all projects, add the following to ~/.claude.json instead:

{
  "mcpServers": {
    "resume-collection": {
      "type": "http",
      "url": "http://localhost:8001/mcp"
    }
  }
}

Stopping

docker compose down

Docker (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-server

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "resume-collection": {
      "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-server

Or create a .env file in the directory you run the server from:

# .env
RESUME_DIR=/path/to/docs
FASTMCP_PORT=8001

Then 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-collection": {
      "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-collection resume-mcp-server -e RESUME_DIR=/path/to/your/resumes

uvx:

{
  "mcpServers": {
    "resume-collection": {
      "command": "uvx",
      "args": ["resume-mcp-server"],
      "env": {
        "RESUME_DIR": "/path/to/your/resumes"
      }
    }
  }
}

Configuration

Docker Compose (.env):

Local run (environment variables or .env):

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.

The server scans RESUME_DIR recursively on startup and reloads automatically when files change.

Document type inference

Types are inferred from filenames:

Search behavior

All search_* tools split the query on whitespace and support two token match modes via the optional mode parameter:

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.

Single-word queries behave identically in both modes.

Pagination

All list_* tools accept limit (default 100) and offset (default 0) parameters and return a consistent envelope:

{"total_count": 247, "items": [...]}

total_count is the full collection size before slicing. To check whether more pages exist: offset + len(items) < total_count.

MCP Tools

list_resume_summaries

List all resumes as lightweight identity records. Use this first to orient and pick a resume_id before fetching details — much more token-efficient than list_resumes.

Returns: paginated envelope — total_count + items, where each item has id, first_name, last_name, email, phone_num.

list_resumes

List all documents, optionally filtered by type.

Returns: paginated envelope — total_count + items.

get_resume

Return the full extracted text of a document.

get_resume_profile

Get a resume's top-level fields (contact info, professional statement, education) without the nested work experience or badge skill lists. Prefer this over get_resume when you need structured contact data rather than raw text.

search_resumes

Full-text search across all documents (case-insensitive), sorted by match count.

search_resumes_by_name

Find resumes by person name (first or last name). Returns minimal identity fields — use the returned id with other tools to fetch full details.

Returns: id, first_name, last_name, email, phone_num.

search_resumes_by_skill

Find which resumes list a given badge skill. Returns resume identity and matched skill names — more token-efficient than list_resumes when filtering by skill.

Returns: id, first_name, last_name, matched_skills.

search_skills

Search badge skills (technologies, tools, languages) by title.

search_work_experiences

Search work experiences by company name, position title, or achievement description bullets. Each result includes a resume_id field identifying which resume the entry belongs to.

list_work_experiences

List work experience entries, optionally scoped to a single resume and/or only current roles.

Returns: paginated envelope — total_count + items.

get_work_experience

Get a single work experience entry with its achievement bullets.

list_achievements

List all achievement bullets, optionally scoped to a single resume.

Returns: paginated envelope — total_count + items.

get_achievement

Get a single achievement bullet by ID.

search_achievements

Search achievement descriptions directly, returning only matching bullets with minimal parent context. More token-efficient than search_work_experiences when you only need matching bullets.

Returns: id, desc, company_name, position_title, work_experience_id, resume_id.

list_badge_skills

List all badge skills, optionally scoped to a single resume.

Returns: paginated envelope — total_count + items.

get_badge_skill

Get a single badge skill by ID.

list_side_projects

List side projects (personal/portfolio projects, distinct from work experience) that demonstrate competency with specific technologies, optionally scoped to a single resume.

Returns: paginated envelope — total_count + items.

get_side_project

Get a single side project by ID, including the technologies it demonstrates.

search_side_projects

Search side projects by name, description, or associated technology. Each result includes a resume_id field identifying which resume the project belongs to.

search_side_projects_by_technology

Find side projects that demonstrate competency with a given technology.

Returns: id, name, description, matched_technologies, resume_id.

list_education

List education entries (degree, institution, year, and relevant coursework/competencies), optionally scoped to a single resume.

Returns: paginated envelope — total_count + items.

get_education

Get a single education entry by ID, including its competencies.

search_education

Search education entries by institution, degree, or competency. Each result includes a resume_id field identifying which resume the entry belongs to.

search_education_by_competency

Find education entries that demonstrate competency with a given skill — useful for matching a candidate's coursework/training to a specific position's requirements.

Returns: id, institution, degree, year, matched_competencies, resume_id.

get_collection_stats

Return aggregate counts and averages across the entire loaded resume collection. Useful for a quick overview before diving into individual records.

No parameters.

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.

get_skill_frequency

Return badge skills ranked by how many resumes list them, in descending order. Useful for identifying the most common technologies across all candidates.

Returns: list of { skill_id, skill_title, resume_count }.

search_resumes_by_skills

Find resumes that have specific skills. Uses the same partial token matching as search_resumes_by_skill, but accepts a list and applies AND/OR logic across the skill queries — e.g. find everyone with both Python and Docker.

Returns: id, first_name, last_name, matched_skills.