🇰🇷 Job Hunting MCP — 한국 취업시장 특화 MCP 서버

GitHub: https://github.com/PracLee/job_hunting_mcp

한국 취업 준비 과정에서 반복되는 서류 작업을 자동화하는 MCP(Model Context Protocol) 서버입니다.

핵심 가치: 이력서/경력기술서/자기소개서를 한 번 입력하면, 공고별·사이트별로 맞춤 변환합니다. 같은 서류를 사이트마다 다시 쓰는 고통을 없앱니다.

사용법: Claude Desktop, ChatGPT Desktop, Gemini CLI 등 MCP 클라이언트에 연결하면 바로 사용할 수 있습니다. 별도 LLM 설치 없이 MCP 클라이언트의 AI가 서류 작성까지 처리합니다.

---

이 MCP가 하는 일

기능	설명
채용공고 관리	6개 사이트에서 공고 검색 + 정규화 저장
프로필 파싱	이력서/경력기술서를 구조화된 마스터 프로필로 변환
적합도 분석	공고-프로필을 5가지 차원으로 매칭 분석
사이트별 양식 변환	원티드/사람인/잡코리아/점핏/그룹바이 양식 복붙 텍스트
경력기술서 맞춤화	공고 요구사항에 맞게 bullet point 재작성
자기소개서 작성	문항 의도 분석 → 소재 추천 → 초안 생성
포트폴리오 정렬	공고 기준으로 프로젝트 관련도 순 재배치
지원 관리	지원 상태 추적 (저장 → 지원 → 합격/불합격)
면접 준비	공고+경력 기반 예상 질문 및 답변 포인트
기업 성장성 분석	DART 재무제표 3개년 + 뉴스 분석 → GROWING/STABLE/DECLINING 판정, 브랜드명 자동 변환

---

빠른 시작

1. 설치

git clone https://github.com/PracLee/job_hunting_mcp.git
cd job_hunting_mcp
npm install
npm run build

2. MCP 클라이언트에 연결하면 끝!

이 MCP 서버는 MCP를 지원하는 AI 클라이언트에 연결하면 바로 사용할 수 있습니다. 별도 LLM 설치가 필요 없습니다 — 클라이언트의 AI가 서류 작성까지 모두 처리합니다.

┌─────────────────────────┐      Tool 호출      ┌──────────────────────┐
│  MCP 클라이언트 (AI)     │ ─────────────────→ │  이 MCP 서버          │
│                         │                     │                      │
│  • Claude Desktop (추천) │                     │  • 공고 검색/정규화    │
│  • Claude Code (CLI)    │  ←───────────────── │  • 프로필 파싱        │
│  • Gemini CLI           │      결과 반환       │  • 매칭 분석          │
│  • 기타 MCP 호환 앱      │                     │  • 양식 변환          │
│                         │                     │  • 지원 관리          │
│                         │                     │                      │
│  서류 작성은 클라이언트   │                     │  데이터 처리 + 로직    │
│  AI가 직접 처리          │                     │                      │
└─────────────────────────┘                     └──────────────────────┘
     여기서 대화하면                                여기서 실행됨

아래에서 사용하는 클라이언트를 골라 설정하세요.

✅ Claude Desktop (추천)

로컬 설정 파일에 JSON을 추가하면 됩니다.

OS	설정 파일 경로
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "job-hunting": {
      "command": "node",
      "args": ["/절대경로/job_hunting_mcp/dist/index.js"]
    }
  }
}

✅ Claude Code (CLI)

claude mcp add job-hunting node /절대경로/job_hunting_mcp/dist/index.js

✅ Gemini CLI

OS	설정 파일 경로
macOS / Linux	~/.gemini/settings.json
Windows	%USERPROFILE%\.gemini\settings.json

Claude Desktop과 동일한 JSON 포맷(mcpServers)을 사용합니다.

⚠️ ChatGPT Desktop

주의: ChatGPT의 MCP 연결은 Claude Desktop처럼 로컬 설정 파일 방식이 아닙니다. 현재(2026.03 기준) 공식 문서에 따르면 Developer Mode → Apps 흐름으로, ChatGPT Business / Enterprise / Edu 요금제의 웹 환경에서 MCP 서버를 등록하는 방식입니다. 개인 사용자용 로컬 stdio 연결은 아직 공식 지원되지 않을 수 있으므로, OpenAI 공식 MCP 문서를 확인하세요.

기타 MCP 호환 클라이언트

MCP 표준(stdio)을 지원하는 앱이면 어디서든 사용 가능합니다. command: "node", args: ["/절대경로/dist/index.js"]로 등록하면 됩니다.

Windows 사용자 참고: 경로 구분자를 \\로 사용하세요. 예: "args": ["C:\\Users\\이름\\job_hunting_mcp\\dist\\index.js"]

3. 환경 설정 (선택사항)

cp .env.example .env

대부분의 경우 .env 설정 없이 바로 사용할 수 있습니다. 아래는 필요한 경우에만 설정합니다:

# 사람인 API 검색 품질을 높이려면 (선택)
SARAMIN_API_KEY=your-saramin-api-key

# DB 저장 위치 변경 (기본: ./data/job_hunting.db)
DB_PATH=./data/job_hunting.db

기업 성장성 분석 (company_analyze) 사용 시

company_analyze 도구는 DART(금융감독원 공시)와 네이버 뉴스 API를 사용합니다. API 키를 설정하지 않으면 도구 호출 시 설정 안내 메시지를 반환합니다.

# DART OpenAPI 키 — 기업 재무제표(매출·영업이익·부채비율 등) 조회
# 발급: https://opendart.fss.or.kr/ → 회원가입 → OpenAPI 신청 (무료, 즉시 발급)
DART_API_KEY=your-dart-api-key

# 네이버 검색 API — 기업 뉴스/보도 검색
# 발급: https://developers.naver.com/apps/ → 애플리케이션 등록 → 사용 API: 검색 선택 (무료)
NAVER_NEWS_CLIENT_ID=your-naver-client-id
NAVER_NEWS_CLIENT_SECRET=your-naver-client-secret

참고: DART API는 국내 상장사(코스피·코스닥)와 외부감사 대상 비상장사의 재무 데이터를 제공합니다. 소규모 스타트업이나 DART 미공시 기업은 재무 데이터 없이 뉴스 분석만 진행됩니다.

4. 개발/테스트

npm run dev    # tsx로 직접 실행 (개발)
npm start      # 빌드된 JS 실행
npm test       # 테스트 (현재 Vitest 전체 스위트)

5. 로컬 HTTP/SSE 서버로 띄우기 (네트워크 연동용)

Gemini, Claude Desktop 등 로컬 프로세스 연결 외에 네트워크 통신(HTTP/SSE)으로 이 MCP 서버를 띄울 수 있도록 기능을 추가했습니다. 기본 3000번 포트로 실행됩니다.

# 종속성 설치
npm install

# 빌드 및 실행
npm run build
npm run start:sse

# 개발 모드로 실행 시
npm run dev:sse

실행 후 브라우저 혹은 외부 MCP 클라이언트에서 http://localhost:3000/sse 엔드포인트로 연결할 수 있습니다.

💡 ChatGPT 등에 ngrok으로 연결하기 (외부망 포워딩)

로컬 서버를 외부 웹 환경(ChatGPT 웹 등)과 연동하고 싶다면, ngrok을 사용하여 포트 포워딩을 할 수 있습니다.

1. 로컬에서 서버 실행 (npm run start:sse : 3000포트)
2. 새로운 터미널 창을 열고 ngrok 실행:

   ngrok http 3000
   

3. 생성된 Forwarding 도메인(https://xxxx.ngrok.app 등)을 복사합니다.
4. ChatGPT GPTs나 타 외부 클라이언트에서 이 MCP 서버를 등록할 때, URL 뒤에 반드시 /sse 를 붙여서 기입합니다. 👉 https://xxxx.ngrok-free.app/sse

---

(고급) 로컬 LLM 연동

대부분의 사용자는 이 섹션이 필요 없습니다. Claude Desktop 등 MCP 클라이언트의 AI가 서류 작성을 처리하기 때문입니다.

아래는 완전 오프라인 환경에서 사용하거나, MCP 서버 내부에서 자체적으로 LLM을 호출하고 싶을 때를 위한 고급 설정입니다.

Ollama

brew install ollama              # macOS
ollama pull qwen2.5              # 한국어 우수 (추천, 최소 16GB RAM)
ollama serve                     # 서버 시작

# .env
LLM_PROVIDER=ollama
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=qwen2.5

LM Studio / vLLM 등 OpenAI 호환 로컬 서버

LLM_PROVIDER=openai-compatible
LOCAL_LLM_BASE_URL=http://localhost:1234/v1
LOCAL_LLM_MODEL=local-model
LOCAL_LLM_API_KEY=not-needed

로컬 LLM 최소 사양

모델	RAM	비고
qwen2.5 7B (Q4)	16GB+	한국어 추천
llama3 8B (Q4)	16GB+	범용
gemma2 9B (Q4)	16GB+	빠듯함, 다른 앱 닫아야
70B 모델	64GB+	고사양 필요

---

사용법 — 실전 플로우

Step 1: 프로필 등록 (최초 1회)

이력서와 경력기술서 텍스트를 입력하면 자동으로 구조화합니다.

"내 이력서 파싱해줘"

→ profile_parse_resume 호출
→ 기술스택, 프로젝트, 경력 연차, 도메인 자동 추출
→ 마스터 프로필 DB 저장

Step 2: 공고 등록

관심 공고를 복붙하거나 온라인 검색합니다.

# 방법 1: 온라인 검색
"서울, Java 백엔드, 3~5년차 공고 찾아줘"
→ jobs_search(keywords: ["Java", "백엔드"], location: "서울", sources: ["wanted", "jumpit", "groupby", "remember"])

"Python/FastAPI 백엔드 공고 찾아줘"
→ jobs_search(keywords: ["Python", "FastAPI"])
→ `sources`를 생략하면 현재 사용 가능한 검색 소스를 모두 조회하고, 결과를 관련도 순으로 정렬
→ 기본값 `auto_save: true` 이므로 온라인 검색 결과도 DB에 upsert되어 반환된 `job_id`로 바로 `match_score_job` 호출 가능

# 방법 2: URL로 상세 조회
"이 공고 상세 보여줘: https://www.wanted.co.kr/wd/12345"
→ jobs_get_detail(job_id: "https://www.wanted.co.kr/wd/12345")

# 방법 3: 텍스트 복붙
"이 공고 등록해줘" + 공고 전문 붙여넣기
→ jobs_add(company_name: "토스", job_title: "서버 개발자", raw_text: "...")

Step 3: 적합도 분석

"이 공고랑 내 프로필 매칭해줘"
→ match_score_job(job_id: "jp_xxx")
→ overall_score + breakdown + scoring_meta 반환
→ 데이터가 비어 있는 축은 50점으로 고정하지 않고 제외하며, `scoring_meta.applied_weights`에 실제 반영된 가중치가 표시됨
→ coverage가 50% 미만이면 `overall_score` 대신 `scoring_meta.provisional_score`, `confidence`, `INSUFFICIENT_DATA` 상태가 반환됨

Step 4: 서류 맞춤화

# 경력기술서
"이 공고에 맞게 경력기술서 수정해줘"
→ resume_tailor(job_id: "jp_xxx")

# 자기소개서
"지원동기 소재 추천해줘"
→ coverletter_brainstorm(job_id: "jp_xxx", question: "지원동기")

"지원동기 초안 써줘"
→ coverletter_generate(job_id: "jp_xxx", question_type: "motivation")

# 포트폴리오
"이 공고 기준으로 프로젝트 순서 재배치해줘"
→ portfolio_reorder(job_id: "jp_xxx")

Step 5: 사이트별 양식 변환 (핵심!)

같은 프로필을 각 사이트 양식에 맞게 자동 변환합니다.

"원티드 양식으로 변환해줘"
→ resume_export(target_platform: "wanted")
→ 한 줄 소개 + 성과 중심 경력 + 기술 태그

"사람인 양식으로 변환해줘"
→ resume_export(target_platform: "saramin")
→ 인적사항 + 경력사항(표) + 학력 + 자격증

"잡코리아 양식으로 변환해줘"
→ resume_export(target_platform: "jobkorea")
→ 이력서 + 경력기술서 분리

"점핏 양식으로 변환해줘"
→ resume_export(target_platform: "jumpit")
→ 기술 중심 프로필 + 프로젝트 카드

"그룹바이 양식으로 변환해줘"
→ resume_export(target_platform: "groupby")
→ 스타트업향 간결 소개 + 기술 태그 + 성과

LLM으로 문장을 보강하려면: resume_export(target_platform: "wanted", enhance_with_llm: true)

Step 6: 지원 관리 & 면접

# 지원 기록
"이 공고 지원 완료로 기록해줘"
→ application_create(job_id: "jp_xxx", status: "applied")

# 상태 변경
"서류 합격했어"
→ application_update_status(application_id: "app_xxx", new_status: "document_passed")

# 현황 조회
"지원 현황 보여줘"
→ application_list

# 면접 준비
"이 회사 면접 준비해줘"
→ interview_prepare(job_id: "jp_xxx")
→ 예상 기술 질문 + 경험 질문 + 답변 포인트

---

Tool 전체 목록

채용공고 (3개)

Tool	설명
jobs_search	키워드/조건으로 공고 검색. auto_save=true 기본값으로 검색 결과를 DB에 upsert하며, search_meta.sources_result_count와 소스별 warnings를 함께 반환
jobs_get_detail	특정 공고 상세 조회 (URL 붙여넣기 지원)
jobs_add	공고 텍스트를 복붙하여 수동 등록

프로필 (7개) - v1.0 엔진 탑재

Tool	설명
profile_parse_resume	이력서/경력기술서 파싱. reset_overrides로 강제 초기화 및 파싱 diff 제공
profile_get	3계층(raw, parsed, confirmed) 엄격 분리 구조로 프로필 전문 조회
profile_update_skills	오인식 스킬 삭제(블랙리스트) 및 보조 스킬 영구 추가(화이트리스트)
profile_update_experience	자유 서술형 텍스트에서 꼬인 총 경력 개월 수 수동 정밀 교정
profile_confirm_skills	자동 추출된(parsed) 전체 기술들을 "검증된(user_confirmed)" 계층으로 승격
profile_list_versions	파싱할 때마다 저장된 과거 이력서 스냅샷(버전) 히스토리 조회
profile_rollback_version	잘못 파싱된 기록을 버리고 특정 과거 버전의 ID를 통해 타임머신 복구

매칭 (2개)

Tool	설명
match_score_job	공고-프로필 5차원 매칭 분석. 축별 점수와 scoring_meta(적용 가중치/제외 축, coverage, confidence) 반환
match_rank_jobs	여러 공고 적합도 순 랭킹

서류 (5개)

Tool	설명
resume_tailor	공고 맞춤 경력기술서 (클라이언트 AI가 처리)
resume_export	플랫폼별 양식 변환 (5개 사이트 + 범용)
coverletter_brainstorm	자소서 소재 추천 (클라이언트 AI가 처리)
coverletter_generate	자소서 초안 생성 (클라이언트 AI가 처리)
portfolio_reorder	공고 기준 프로젝트 재배치 (클라이언트 AI가 처리)

지원 관리 (3개)

Tool	설명
application_create	지원 기록 생성
application_update_status	상태 변경
application_list	현황 목록 + 통계

면접 (1개)

Tool	설명
interview_prepare	예상 질문/답변 포인트 (클라이언트 AI가 처리)

기업 분석 (1개)

Tool	설명
company_analyze	DART 재무제표 + 네이버 뉴스로 기업 성장성 평가 (GROWING / STABLE / DECLINING)

company_analyze 상세

• 데이터 소스: DART 금융감독원 전자공시(재무제표 3개년) + 네이버 뉴스(최근 N일)
• 지원 범위: 국내 상장사(코스피·코스닥), 외부감사 비상장사, 국내 입점 외국계 법인
• 브랜드명 자동 변환: 별칭/브랜드명 → 법인명 자동 매핑 (예: 배민 → 우아한형제들, 토스 → 비바리퍼블리카)
• 신뢰도 반환: search_path + confidence(high/medium/low/none)로 검색 경로 투명하게 공개
• API 키 미설정 시: 도구 호출 시점에 발급 안내 메시지 반환 (서버 재시작 불필요)

입력: "배민"
  → 브랜드맵: 배민 → 우아한형제들
  → DART: corp_code 조회 + 3개년 재무제표
  → 네이버 뉴스: 최근 90일 관련 기사
  → LLM 종합 분석 → GROWING / STABLE / DECLINING

DART_API_KEY, NAVER_NEWS_CLIENT_ID, NAVER_NEWS_CLIENT_SECRET 설정 필요. 키 미설정 시 도구 호출 시점에 발급 안내를 반환합니다.

---

채용 사이트 지원 현황

사이트	공고 검색	양식 변환	API 키 필요	비고
원티드	✅	✅	불필요	웹 API
사람인	✅	✅	선택 (SARAMIN_API_KEY)	API 우선, 미설정 시 웹 크롤링 폴백
잡코리아	✅	✅	불필요	웹 파싱
점핏	✅	✅	불필요	웹 API
그룹바이	✅	✅	불필요	스타트업 전문, Next.js SSR 파싱
리멤버	✅	-	불필요	경력직 전문, 내부 API 파싱

검토 후 제외한 플랫폼

플랫폼	제외 이유
로켓펀치	서비스 종료
혁신의숲	채용 플랫폼이 아님 (스타트업 분석). 채용은 원티드 연동이라 중복
위시캣	프리랜서 프로젝트 매칭 전문. 정규직 채용 스키마와 구조 불일치

---

기술 스택

구분	기술
Runtime	Node.js 18+ (권장 20+)
Language	TypeScript (strict)
MCP SDK	@modelcontextprotocol/sdk
DB	SQLite (better-sqlite3) — 로컬 파일, 별도 설치 불필요
LLM	MCP 클라이언트 AI 사용 (고급: Ollama / LM Studio 로컬 연동 가능)
Validation	Zod
Test	Vitest (68건)

---

프로젝트 구조

src/
├── index.ts                  # 진입점
├── server.ts                 # MCP 서버 설정
├── tools/                    # MCP Tool 레이어 (입력 검증/응답 직렬화)
│   ├── jobs/                 # 채용공고 검색/추가
│   ├── profile/              # 프로필 파싱
│   ├── match/                # 적합도 분석
│   ├── resume/               # 경력기술서 맞춤화 + 양식 변환
│   ├── coverletter/          # 자기소개서
│   ├── portfolio/            # 포트폴리오 정렬
│   ├── application/          # 지원 관리
│   └── interview/            # 면접 준비
├── services/                 # 도메인 서비스 레이어
│   ├── jobs-service.ts       # 검색 집계/정렬
│   ├── profile-service.ts    # 프로필 파싱/교정
│   ├── match-service.ts      # 매칭 분석
│   ├── resume-service.ts     # 이력서 맞춤화/변환
│   └── ...                   # coverletter/company/application 등
├── adapters/                 # 채용 사이트별 어댑터
│   ├── base-adapter.ts       # 공통 인터페이스
│   ├── wanted-adapter.ts     # 원티드
│   ├── saramin-adapter.ts    # 사람인
│   ├── jobkorea-adapter.ts   # 잡코리아
│   ├── jumpit-adapter.ts     # 점핏
│   ├── groupby-adapter.ts    # 그룹바이 (스타트업)
│   └── remember-adapter.ts   # 리멤버 (경력직)
├── core/                     # 핵심 라이브러리
│   ├── llm-client.ts         # LLM 추상화 (Ollama / OpenAI 호환 로컬)
│   ├── tech-dictionary.ts    # 기술 사전 (80+ 항목, 한국어 동의어)
│   ├── resume-parser.ts      # 이력서 규칙 기반 파싱
│   ├── job-normalizer.ts     # 공고 텍스트 정규화
│   ├── job-search.ts         # 공고 검색 relevance 점수 계산
│   ├── match-scoring.ts      # 적합도 계산 로직
│   ├── platform-templates.ts # 플랫폼별 양식 템플릿 (6종)
│   └── utils.ts
├── db/                       # SQLite DB
│   ├── connection.ts
│   └── repositories/
└── types/                    # 타입 정의

tests/                        # 테스트
├── services/                 # 서비스/코어 로직 테스트
└── tools/                    # E2E 통합 테스트

---

설계 원칙

1. MCP 클라이언트 우선 — Claude Desktop/ChatGPT 등에 연결하면 바로 사용. 별도 LLM 설치 불필요
2. 규칙 기반 핵심 — 검색/매칭/양식 변환은 규칙 기반. AI는 서류 생성에만
3. 허위 경험 금지 — 기존 경험을 재구성/강조하는 방향으로만 지원
4. 한국 시장 특화 — 한국식 이력서/자소서/채용공고 구조에 맞춤
5. 확장 가능 — 새 채용 사이트 추가 = SourceAdapter 구현 1개
6. 비개발자 친화 — 설치 후 대화만으로 모든 기능 사용 가능

---

피드백 및 문의

이 프로젝트의 기획 배경과 개발 회고는 아래 글에서 확인하실 수 있습니다:

• 📝 프로젝트 회고록 (Tistory)

사용 중 발견한 버그, 부족한 점, 개선 아이디어 등 피드백이 있다면 위 블로그의 댓글로 자유롭게 남겨주세요!

---

변경 이력

v1.1.0 (2026-04-01)

프로필 스키마 확장

• total_experience_months 필드 추가 — 경력을 연 단위 외 월 단위로도 저장
• user_confirmed_skills / user_rejected_skills 필드 추가 — 스킬 확정/거부 워크플로우 지원
• 기존 DB 자동 마이그레이션 (ALTER TABLE)

이력서 파서 정확도 전면 개선

• 섹션 헤더 판단 강화: 기술 스택: Python, ... 같이 : 뒤 내용이 있는 줄을 헤더로 잘못 인식하던 버그 수정 → 프로젝트 섹션 중간 절단 현상 해소
• 경력 연차 계산: 총 N년 N개월 패턴 1순위 적용, months 값 동시 반환
• 이름 추출: 이병재 경력 같은 채용사이트 복합 형식에서 이름 추출 가능
• 프로젝트 제목 감지: bullet(-, •) 으로 시작하는 줄을 프로젝트 제목으로 오인하던 버그 수정
• 기술스택 추출: 기술 단독 키워드 매치 방지 → 기술 스택: 명시 형태만 허용
• 학력 전공 파싱: 학과? 패턴이 학교명(협성대학교)을 전공으로 오인하던 버그 수정
• 프로젝트 유효성 필터 추가: 학력, 보유 기술 등 섹션 헤더 및 개인정보 블록이 프로젝트로 등록되던 문제 해소

---

문제 해결

better-sqlite3 버전 불일치 오류 (NODE_MODULE_VERSION mismatch)

증상: MCP 서버 실행 시 아래와 같은 오류 발생

Error: The module '...better_sqlite3.node' was compiled against a different Node.js version

원인: better-sqlite3는 네이티브 바이너리로, 빌드한 Node.js 버전과 실행 환경의 Node.js 버전이 다르면 충돌합니다. Claude Desktop Cowork 같은 환경은 내부적으로 별도의 Node.js 버전을 사용하는 경우가 있습니다.

해결법: 실행 환경의 Node.js 버전으로 맞춰서 rebuild

nvm이 없다면 먼저 설치하세요: https://github.com/nvm-sh/nvm LLM 클라이언트마다 요구하는 Node.js 버전이 다를 수 있으므로, nvm으로 버전을 전환하는 것을 권장합니다.

# 실행 환경 Node 버전 확인 후 해당 버전으로 rebuild
nvm install 22   # 없으면 설치
nvm use 22
cd /path/to/job_hunting_mcp
npm rebuild better-sqlite3

이후 MCP 클라이언트(Claude Desktop 등)를 재시작하면 정상 동작합니다.

---

라이선스

MIT