Salary MCP Server (salary-mcp)

LLM に Djinni (djinni.co) と DOU (jobs.dou.ua/salaries/) の実際の公開 IT 市場給与ベンチマークへの直接的かつプログラム的なアクセスを提供する Model Context Protocol (MCP) サーバー。

⚡ クイックスタート（公開済み 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 経由で実行（リモートサーバー）

リモートデプロイ、コンテナ、Web クライアント向けの 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 の公式ライブ Web ポータルから排他的にデータを取得します：

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. カテゴリ集約と特定タイトルフィルタリング:

   • Web インターフェースで広範なカテゴリ（例：「Data & Analytics」や「Management」）を選択すると、すべてのサブ職種がまとめて集約されます。

   • 特定のタイトルクエリ（例：Middle Data Scientist や Junior HR Specialist）は、データセット内の特定のタイトル層に一致します。

3. 調査ウェーブのリリース:

   • デフォルトでは、salary-mcp は常に最新の公式調査ウェーブ（例：2026-06）を選択します。ウェブサイトのユーザーインターフェースが以前のウェーブや別の記事を表示している場合、as_of_date を指定することで完全に一致することが保証されます。

🛠️ MCP ツールリファレンス

get_djinni_salaries

Djinni からリアルタイムの候補者の給与期待値と求人オファー分布を取得します。

• 引数:

  • role (文字列、必須): 対象の職種（例："Software Engineer"、"QA"、"DevOps"、"HR"）。

  • specialization (文字列、任意): 技術またはドメイン（例："Python"、"React"、"HR"）。

  • experience_years (整数、任意): 経験年数（例：0、2、5）。

  • english_level (文字列、任意): 英語レベル（例："intermediate"、"advanced"）。

get_dou_salaries

DOU から公式の給与調査ベンチマークとパーセンタイルを取得します。

• 引数:

  • role (文字列、必須): 職種またはカテゴリ（例："Software Engineer"、"Data Science"）。

  • specialization (文字列、任意): 言語またはサブ職種（例："Python"、"Data Scientist"）。

  • experience_years (整数、任意): 実務経験年数。

  • seniority (文字列、任意): シニアレベル（"Junior"、"Middle"、"Senior"、"Lead"、"Architect"）。

  • city (文字列、任意): ロケーションフィルター（例："Kyiv"、"Lviv"、"Remote"）。

  • as_of_date (文字列、任意): YYYY-MM 形式の調査日（例："2025-12"、"2026-06"）。デフォルトは最新。

compare_salaries

Djinni と DOU の給与ベンチマークを差分分析とともに並べて比較します。

• 引数:

  • role (文字列、必須): 対象の職種。

  • specialization (文字列、任意): 技術または専門分野。

  • experience_years (整数、任意): 経験年数。

  • seniority (文字列、任意): DOU のマッチングに使用するシニアレベル。

  • as_of_date (文字列、任意): DOU 比較の対象調査日。

list_specializations

利用可能な職種、技術、シニアレベル、場所、過去の調査日を一覧表示します。

• 引数:

  • provider (文字列、任意): 選択肢のスコープ（"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 をご覧ください。