resume-mcp-server

An MCP server for browsing and searching job application documents — resumes, cover letters, and related materials.

Supports .docx, .pdf, .md, and .txt files, including nested subdirectories.

Quick Start

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

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:

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.

No parameters.

Returns: id, first_name, last_name, email, phone_num for each resume.

list_resumes

List all documents, optionally filtered by type.

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.

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.

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.

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.

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.

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.