Job Matcher MCP

🎯 AI 기반 구직 및 이력서 맞춤화 MCP (Model Context Protocol) 서버

채용 API와 Claude LLM을 활용하여 구직 활동을 자동화하고 각 직무에 맞게 이력서를 1분 이내에 맞춤화하세요.

📋 목차

• 빠른 시작 (5분)

• 기능

• 설치

• 설정

• 사용법

• MCP 도구 참조

• 아키텍처

• 문제 해결

🚀 빠른 시작

목표: API 키 없이 5분 안에 모의 데이터로 서버 실행하기

1. 저장소 클론

```bash cd job-matcher-mcp ```

2. 의존성 설치

```bash pip install -r requirements.txt ```

3. 모의 데이터로 실행

```bash export USE_MOCK_DATA=true python mcp_server.py ```

예상 출력: `` === Testing search_jobs === { "success": true, "job_listings": [ { "id": "mock_1", "title": "Senior Product Manager", "company": "TechCorp Inc", "location": "San Francisco, CA", ... } ], ... }

=== Testing customize_resume === { "success": true, "customized_resume": "# John Doe...", ... } `

✅ 성공! MCP 서버가 작동 중입니다. 이제 실제 API 키를 추가해 보겠습니다.

✨ 기능

🔧 설치

사전 요구 사항

• Python 3.10 이상

• pip (Python 패키지 관리자)

• Git

1단계: 저장소 클론

```bash git clone https://github.com/yourusername/job-matcher-mcp.git cd job-matcher-mcp ```

2단계: 가상 환경 생성 (권장)

```bash

macOS/Linux

python3 -m venv venv source venv/bin/activate

Windows

python -m venv venv .\venv\Scripts\Activate.ps1 ```

3단계: 의존성 설치

```bash pip install -r requirements.txt ```

⚙️ 설정

1. API 키 받기

Adzuna API (무료)

1. https://developer.adzuna.com/ 방문

2. 계정 생성

3. 앱을 만들어 App ID 및 App Key 받기

4. 무료 티어: 하루 약 100회 요청

Anthropic Claude API (유료, 월 $0.50~$5)

1. https://console.anthropic.com/ 방문

2. 계정 생성

3. API 키 생성

4. 가격: 입력 토큰 1K당 약 $0.003, 출력 토큰 1K당 $0.015

2. .env 파일 생성

```bash cp .env.example .env ```

3. .env에 API 키 추가

```env ADZUNA_APP_ID=your_actual_app_id ADZUNA_APP_KEY=your_actual_app_key ANTHROPIC_API_KEY=sk-ant-your_actual_api_key USE_MOCK_DATA=false LOG_LEVEL=INFO ```

4. 환경 변수 로드

```bash

macOS/Linux

export $(grep -v '^#' .env | xargs)

Windows PowerShell

Get-Content .env | ForEach-Object { $name, $value = $_.Split('=') if ($name) { Set-Item -Path env:$name -Value $value } } ```

💻 사용법

서버 실행

```bash python mcp_server.py ```

curl로 테스트 (예시)

```bash

구직 검색

curl -X POST http://localhost:8000/tools/search_jobs
-H "Content-Type: application/json"
-d '{ "role": "Product Manager", "location": "San Francisco, CA", "experience_years": 5, "max_results": 10 }'

이력서 맞춤화

curl -X POST http://localhost:8000/tools/customize_resume
-H "Content-Type: application/json"
-d '{ "base_resume": "...", "job_description": "...", "template": "modern" }' ```

Python 예시

```python from mcp_server import JobMatcherMCPServer

server = JobMatcherMCPServer()

구직 검색

jobs = server.search_jobs( role="Product Manager", location="San Francisco, CA", experience_years=5, max_results=10 ) print(jobs)

이력서 맞춤화

resume = server.customize_resume( base_resume="Your resume text here...", job_description="Job description here...", template="modern" ) print(resume) ```

🛠️ MCP 도구 참조

도구 1: search_jobs

조건에 따라 채용 공고를 검색합니다.

입력 스키마

```json { "role": "Product Manager", // 필수: 직무명 "location": "San Francisco, CA", // 필수: 지리적 위치 "experience_years": 5, // 필수: 경력 연수 "max_results": 10, // 선택: 결과 제한 (기본값: 10) "use_mock_data": false // 선택: 모의 데이터 사용 (기본값: false) } ```

출력 스키마

```json { "success": true, "job_listings": [ { "id": "12345", "title": "Senior Product Manager", "company": "TechCorp", "location": "San Francisco, CA", "link": "https://...", "salary_min": 120000, "salary_max": 160000, "posted_date": "2026-08-17T10:00:00Z", "description_snippet": "We are looking for..." } ], "total_found": 123, "search_time_ms": 1234, "error": null } ```

예시

```python jobs = server.search_jobs( role="Product Manager", location="Remote", experience_years=3, max_results=5 ) ```

도구 2: customize_resume

AI를 사용하여 특정 직무에 맞게 이력서를 맞춤화합니다.

입력 스키마

```json { "base_resume": "# Jane Doe...", // 필수: 이력서 텍스트 "job_description": "We are looking for...", // 필수: 채용 공고 "template": "modern", // 선택: modern|classic|minimal "use_mock_data": false // 선택: 모의 데이터 사용 } ```

출력 스키마

```json { "success": true, "customized_resume": "# Jane Doe...", "match_analysis": { "skills_match_percentage": 82, "matched_skills": ["Product Management", "Leadership"], "missing_skills": ["Machine Learning", "Cloud"], "suggestions": ["Add ML experience if applicable"], "keywords_added": ["Data-driven", "Cross-functional"] }, "generation_time_ms": 2345, "error": null } ```

예시

```python customized = server.customize_resume( base_resume=open("resume.txt").read(), job_description=open("job_posting.txt").read(), template="modern" ) ```

🏗️ 아키텍처

┌─────────────────────────────────────────────────────┐
│  사용자/AI 에이전트 (채팅, 스크립트, API 클라이언트)          │
└────────────────┬────────────────────────────────────┘
                 │ MCP 프로토콜
┌────────────────▼────────────────────────────────────┐
│         Job Matcher MCP 서버                      │
│ ┌──────────────────────────────────────────────┐   │
│ │  도구: search_jobs()                         │   │
│ │  - Adzuna API 쿼리                          │   │
│ │  - 결과 파싱 및 구조화                 │   │
│ └──────────────────────────────────────────────┘   │
│ ┌──────────────────────────────────────────────┐   │
│ │  도구: customize_resume()                    │   │
│ │  - Claude API로 전송                        │   │
│ │  - 맞춤화된 이력서 파싱 및 반환          │   │
│ └──────────────────────────────────────────────┘   │
│ ┌──────────────────────────────────────────────┐   │
│ │  외부 API                               │   │
│ │  - Adzuna 구직 검색 API                     │   │
│ │  - Anthropic Claude API                      │   │
│ └──────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────┘

🔍 문제 해결

문제: ModuleNotFoundError: No module named 'anthropic'

해결 방법: 의존성 설치 ```bash pip install -r requirements.txt ```

문제: API request failed: Unauthorized

해결 방법: .env 파일의 API 키 확인 ```bash

키가 설정되었는지 확인

echo $ADZUNA_APP_ID echo $ANTHROPIC_API_KEY ```

문제: No jobs found

해결 방법: 다른 직무/지역을 시도하거나 max_results 증가 ```python

더 넓은 검색 시도

jobs = server.search_jobs( role="Manager", # 더 일반적인 용어 location="New York, NY", experience_years=5, max_results=50 ) ```

문제: Claude API response too slow

해결 방법: 테스트 시 모의 데이터 사용 ```python resume = server.customize_resume( base_resume="...", job_description="...", use_mock_data=True # API 호출 건너뛰기 ) ```

문제: Rate limit exceeded

해결 방법: Adzuna 무료 티어에는 제한이 있습니다. 캐싱 구현: ```python

구직 검색 결과 저장

cached_jobs = {} key = f"{role}{location}{experience_years}" if key not in cached_jobs: cached_jobs[key] = server.search_jobs(...) ```

🚢 배포

Vercel에 배포

```bash

1. https://vercel.com에서 Vercel 계정 생성

2. Vercel CLI 설치

npm install -g vercel

3. 배포

vercel

4. Vercel 대시보드에서 환경 변수 추가

Settings → Environment Variables

```

Railway에 배포

```bash

1. https://railway.app에서 Railway 계정 생성

2. Git 저장소 연결

3. Railway 대시보드에서 환경 변수 추가

```

📊 성능 지표 (목표)

📚 API 참조

• Adzuna API: https://developer.adzuna.com/docs

• Claude API: https://docs.anthropic.com/

• MCP 프로토콜: https://modelcontextprotocol.io/

📝 라이선스

MIT 라이선스 - 자세한 내용은 LICENSE 파일 참조

👨‍💼 저자

직무 전환 중인 기술 제품 관리자를 위해 제작되었습니다.

버전: 1.0.0
마지막 업데이트: 2026-08-17
상태: MVP 준비 완료