Salary MCP Server (salary-mcp)

Model Context Protocol (MCP)를 기반으로 하는 서버로, 실제 공개 IT 시장 연봉 벤치마크를 Djinni (djinni.co) 및 **DOU (jobs.dou.ua/salaries/)**에서 직접 프로그래밍 방식으로 가져와 LLM에 제공합니다.

⚡ 빠른 시작 (배포된 PyPI 패키지)

salary-mcp는 PyPI에 게시되어 있으며 수동으로 리포지토리를 클론할 필요 없이 즉시 실행할 수 있습니다.

1. Stdio로 실행 (기본값)

데스크톱 AI 클라이언트(Claude Desktop, Cursor, Antigravity, Zed)를 위한 표준 입력/출력 통신:

# Instant run with uvx (no installation needed)
uvx salary-mcp

# Or with pipx
pipx run salary-mcp

# Or install via pip
pip install salary-mcp
salary-mcp

2. HTTP / SSE로 실행 (원격 서버)

원격 배포, 컨테이너 및 웹 클라이언트를 위한 Server-Sent Events (SSE) 모드:

# Start SSE HTTP server on port 8000
uvx salary-mcp --transport sse --host 0.0.0.0 --port 8000

MCP 클라이언트는 http://localhost:8000/sse에 연결할 수 있습니다:

Related MCP server: PayHub MCP Server

🔌 MCP 클라이언트 구성

Claude Desktop (claude_desktop_config.json)

Stdio 모드 (권장):

{
  "mcpServers": {
    "salary-mcp": {
      "command": "uvx",
      "args": ["salary-mcp"]
    }
  }
}

HTTP / SSE 모드:

{
  "mcpServers": {
    "salary-mcp": {
      "url": "http://localhost:8000/sse"
    }
  }
}

Cursor (~/.cursor/mcp.json)

{
  "mcpServers": {
    "salary-mcp": {
      "command": "uvx",
      "args": ["salary-mcp"]
    }
  }
}

🌐 데이터 소스 및 추출 아키텍처

서버는 오직 Djinni와 DOU의 실시간 공식 웹 포털에서만 데이터를 가져옵니다:

1. Djinni (https://djinni.co/salaries/)

• 엔드포인트 형식: https://djinni.co/salaries/?category={category}&exp={exp}&english_level={level}

• 추출 방식: Djinni의 롤링 30일 플랫폼 채용 지표를 요청 시 실시간 스크래핑.

• 추출 데이터:

  • 후보자 기대 연봉: 25~75 백분위수 기대 연봉 및 계산된 중앙값.

  • 기업 채용 공고: 활성 구인 공고의 연봉 제안 범위.

  • 시장 활동: 온라인 활성 후보자 및 공개 채용 공고 수의 실시간 카운터.

  • 연봉 분포: 임베디드 차트 데이터에서 직접 파싱한 전체 연봉 구간 히스토그램.

2. DOU (https://jobs.dou.ua/salaries/)

• 엔드포인트 소스: https://jobs.dou.ua/salaries/가 직접 로드하는 마스터 위젯 데이터셋 (https://s.dou.ua/files/lenta/salary-widget_jun_2026_v3/data/swd-medians.csv).

• 추출 방식: 공식 통계 사분위수($q1$, $median$, $q3$), 응답자 표본 크기($count$) 및 시니어티 직급 수준($title$)을 슬라이스합니다.

• 과거 데이터 지원: as_of_date 파라미터를 통해 특정 과거 설문 웨이브를 조회할 수 있으며 (예: '2025-12', '2026-06'), 기본값은 사용 가능한 최신 웨이브입니다.

❓ DOU 제공 데이터가 웹사이트 UI 보기와 다를 수 있는 이유

salary-mcp로 DOU를 조회할 때, 반환된 통계와 jobs.dou.ua/salaries/의 인터랙티브 UI에 표시되는 내용 사이에 미묘한 차이가 때때로 발견될 수 있습니다:

1. 프론트엔드 표본 크기 임계값:

   • 공개 웹사이트에서 DOU의 차트 스크립트는 종종 최소 표본 크기 임계값(일반적으로 $\ge 15-20$ 명의 응답자)을 적용합니다.

   • 특정 경력 구간에 응답자가 더 적은 경우(예: Data Science 분야 9년 경력에 $11$ 명의 응답자), 웹사이트 차트는 막대를 "Недостатньо анкет" (데이터 부족)으로 숨기거나 회색으로 표시합니다.

   • 기본 DOU 분석 데이터셋은 해당 응답자들에 대해 정확히 계산된 중앙값을 보존하며, salary-mcp는 이를 정확하게 반환합니다.

2. 카테고리 집계 vs. 특정 직함 필터링:

   • 웹 인터페이스에서 넓은 카테고리(예: "Data & Analytics" 또는 "Management")를 선택하면 모든 하위 역할이 함께 집계됩니다.

   • 특정 직함 쿼리(예: Middle Data Scientist 또는 Junior HR Specialist)는 데이터셋 내의 특정 직함 등급과 일치합니다.

3. 설문 웨이브 릴리스:

   • 기본적으로 salary-mcp는 항상 가장 최근 공식 설문 웨이브(예: 2026-06)를 선택합니다. 웹사이트 사용자 인터페이스가 이전 웨이브나 다른 기사를 표시하는 경우, as_of_date를 지정하면 완전히 동일하게 맞출 수 있습니다.

🛠️ MCP 도구 참조

get_djinni_salaries

Djinni에서 실시간 후보자 기대 연봉 및 채용 공고 연봉 분포를 가져옵니다.

• 인자:

  • role (string, 필수): 대상 직무 역할 (예: "Software Engineer", "QA", "DevOps", "HR").

  • specialization (string, 선택): 기술 또는 도메인 (예: "Python", "React", "HR").

  • experience_years (integer, 선택): 경력 연수 (예: 0, 2, 5).

  • english_level (string, 선택): 영어 숙련도 (예: "intermediate", "advanced").

get_dou_salaries

DOU에서 공식 연봉 설문 벤치마크와 백분위수를 가져옵니다.

• 인자:

  • role (string, 필수): 직무 역할 또는 카테고리 (예: "Software Engineer", "Data Science").

  • specialization (string, 선택): 언어 또는 하위 역할 (예: "Python", "Data Scientist").

  • experience_years (integer, 선택): 전문 경력 연수.

  • seniority (string, 선택): 시니어티 등급 ("Junior", "Middle", "Senior", "Lead", "Architect").

  • city (string, 선택): 위치 필터 (예: "Kyiv", "Lviv", "Remote").

  • as_of_date (string, 선택): YYYY-MM 형식의 설문 날짜 (예: "2025-12", "2026-06"). 기본값은 최신입니다.

compare_salaries

Djinni와 DOU 간 연봉 벤치마크를 차이 분석과 함께 나란히 비교합니다.

• 인자:

  • role (string, 필수): 대상 직무 역할.

  • specialization (string, 선택): 기술 또는 전문 분야.

  • experience_years (integer, 선택): 경력 연수.

  • seniority (string, 선택): DOU 매칭을 위한 시니어티 수준.

  • as_of_date (string, 선택): DOU 비교를 위한 대상 설문 날짜.

list_specializations

사용 가능한 역할, 기술, 시니어티, 위치 및 과거 설문 날짜를 나열합니다.

• 인자:

  • provider (string, 선택): 선택 범위 ("all", "djinni", "dou"). 기본값은 "all"입니다.

🛠️ 로컬 개발

# Clone and install dependencies
git clone https://github.com/propsi4/salary-mcp.git
cd salary-mcp
poetry install

# Run test suite
poetry run pytest

# Run linter and type checks
poetry run ruff check . --fix
poetry run ruff format .
poetry run mypy src tests

📄 라이선스

MIT 라이선스. 자세한 내용은 LICENSE를 참조하세요.