Resume MCP

An MCP (Model Context Protocol) server that gives any compatible AI assistant two tools:

• get_master_resume — loads a master resume JSON file that the AI uses as its source of truth
• generate_resume — takes the AI's tailored resume JSON and renders it to a PDF using headless Chromium

When you paste a job description into your AI client, the server's system prompt instructs it to autonomously fetch your master resume, tailor it for the role, and generate a PDF — no extra prompting needed.

---

How It Works

This server implements the MCP specification over HTTP using Server-Sent Events (SSE). It includes a full OAuth 2.0 authorization code + PKCE flow so it can be connected to remote AI clients like claude.ai.

AI Client (claude.ai, Cursor, etc.)
    ↓  OAuth 2.0 + PKCE
Resume MCP Server  (this repo)
    ↓  reads JSON
Master Resume Files  (your data/ directory)
    ↓  writes PDF
Output Directory  (your output/ directory)

---

Prerequisites

• Docker (recommended) — handles all dependencies including Chromium automatically
• OR Node.js 20+ with pnpm and a local Chrome or Chromium installation
• A publicly accessible URL if connecting to a remote AI client (e.g. ngrok, Cloudflare Tunnel, or a VPS)

---

Chrome / Chromium

PDF generation requires a Chrome or Chromium binary. Docker handles this for you — Chromium is installed in the container and no configuration is needed.

For local (non-Docker) runs, you need Chrome or Chromium installed on your machine:

• macOS / Windows — Google Chrome is almost certainly already installed
• Ubuntu/Debian — sudo apt install chromium-browser
• Arch — sudo pacman -S chromium

The server auto-detects common binary names (google-chrome, chromium, chromium-browser). You only need to set CHROME_PATH if it isn't found automatically — which is rare.

---

Quick Start (Docker)

1. Clone the repo

git clone <repo-url> resume-mcp
cd resume-mcp

2. Create your environment file

cp .env.example .env

Edit .env and set at minimum:

OAUTH_CLIENT_ID=resume-mcp-client

This value must match what your MCP client sends as client_id during the OAuth flow. For claude.ai it will be set automatically; for other clients check their MCP documentation.

3. Add your master resume

mkdir -p data/master-resumes output

Place your master resume at data/master-resumes/default.json. This is what the AI loads when you call get_master_resume without an owner argument.

You can store multiple resumes for different people:

data/master-resumes/
  default.json      ← loaded when no owner is specified
  alice.json        ← loaded with { "owner": "alice" }
  bob.json          ← loaded with { "owner": "bob" }

See Master Resume Format for the JSON schema.

4. Build and run

docker compose up --build

The server starts on http://localhost:7331 by default.

5. Expose it publicly (required for remote AI clients)

The server must be reachable from the internet for clients like claude.ai. Use ngrok or any tunnel:

ngrok http 7331

Copy the https:// forwarding URL — you'll use it when adding this server to your AI client.

6. Connect your AI client

Add this server to your MCP client using the public URL. The client will walk you through OAuth authorization on first connection, which writes a token to data/oauth_tokens.json.

---

Running Without Docker

Requires Node.js 20+, pnpm, and Chrome/Chromium on your machine (see Chrome / Chromium above).

pnpm install
pnpm start       # production
pnpm dev         # watch mode, restarts on file changes

---

Environment Variables

Variable	Default	Description
OAUTH_CLIENT_ID	(required)	Client ID accepted during OAuth. Must match your MCP client.
OAUTH_CLIENT_SECRET	(empty)	Optional client secret. Leave blank to skip secret verification.
MCP_HOST	127.0.0.1	Bind address. Set to 0.0.0.0 to accept external connections (Docker sets this automatically).
MCP_PORT	7331	Port the server listens on.
DATA_DIR	Platform data dir	Root directory for oauth_tokens.json and the default master-resumes/ subdirectory.
MASTER_RESUME_DIR	$DATA_DIR/master-resumes	Directory containing master resume JSON files.
MASTER_RESUME_PATH	(unset)	Path to a single default master resume file. Overrides MASTER_RESUME_DIR for the default owner.
GENERATED_RESUME_DIR	Platform documents dir	Where generated PDFs are saved.
CHROME_PATH	Auto-detected	Path to Chrome or Chromium binary. Only needed if auto-detection fails.

---

Master Resume Format

The master resume is a JSON object. The AI uses this as its source of truth and reorganizes/trims it when tailoring for a specific role.

{
  "name": "Jane Smith",
  "location": "San Francisco, CA",
  "email": "jane@example.com",
  "phone": "555-555-5555",
  "linkedin": "https://linkedin.com/in/janesmith",
  "github": "https://github.com/janesmith",
  "portfolio": "https://janesmith.dev",

  "sections": [
    {
      "name": "Technical Skills",
      "type": "grouped",
      "items": [
        { "title": "Languages", "bullets": ["TypeScript", "Python", "Go"] },
        { "title": "Frameworks", "bullets": ["React", "Node.js", "FastAPI"] },
        { "title": "Infrastructure", "bullets": ["Docker", "AWS", "PostgreSQL"] }
      ]
    },
    {
      "name": "Experience",
      "type": "timeline",
      "items": [
        {
          "title": "Acme Corp",
          "sub_title": "San Francisco, CA",
          "position": "Senior Software Engineer",
          "start_date": "2022",
          "end_date": "Present",
          "bullets": [
            "Led migration from monolith to microservices, reducing deploy time by 60%",
            "Built real-time data pipeline processing 2M events/day using Kafka and Go"
          ]
        }
      ]
    },
    {
      "name": "Projects",
      "type": "timeline",
      "items": [
        {
          "title": "My Project",
          "sub_title": "TypeScript, React, PostgreSQL",
          "link": "https://github.com/janesmith/my-project",
          "start_date": "2023",
          "end_date": "Present",
          "bullets": [
            "Description of the project and its impact"
          ]
        }
      ]
    },
    {
      "name": "Education",
      "type": "timeline",
      "items": [
        {
          "title": "State University",
          "sub_title": "City, State",
          "start_date": "2016",
          "end_date": "2020",
          "bullets": ["B.S. Computer Science"]
        }
      ]
    }
  ]
}

Section types:

• "grouped" — renders as a skill list (Title: item, item, item)
• "timeline" — renders as dated entries with bullets (used for experience, projects, education)

Tips for a strong master resume:

• Include everything — the AI removes irrelevant content when tailoring. More is better here.
• Use specific, measurable bullets ("reduced latency by 40%" beats "improved performance").
• List all technologies you've actually used, even if minor — the AI will surface the right ones.

---

Generated PDFs

PDFs are written to the output/ directory (or GENERATED_RESUME_DIR). When running via Docker, this is a mounted volume so files appear on your host machine immediately after generation.

The AI names files descriptively: Jane Smith - Senior Engineer - Acme Corp.pdf

---

OAuth Notes

The server implements OAuth 2.0 authorization code flow with PKCE (S256). On first connection, your AI client will redirect you through an authorization page and store the resulting token locally. Tokens expire after 30 days, after which you'll need to re-authorize.

OAuth tokens are persisted in data/oauth_tokens.json. Do not commit this file.

---

Multiple Users

To support multiple people generating resumes from the same server, add a named JSON file per person to data/master-resumes/:

data/master-resumes/alice.json
data/master-resumes/bob.json

Then instruct the AI to use a specific owner:

"Generate a resume for alice targeting this job description: ..."

The AI will call get_master_resume with { "owner": "alice" }.