Salary MCP Server (salary-mcp)

A Model Context Protocol (MCP) server providing LLMs with direct, programmatic access to actual public IT market salary benchmarks from Djinni (djinni.co) and DOU (jobs.dou.ua/salaries/).

---

⚡ Quick Start (Published PyPI Package)

salary-mcp is published on PyPI and can be run instantly without manual repository cloning.

1. Run over Stdio (Default)

Standard input/output communication for desktop AI clients (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. Run over HTTP / SSE (Remote Server)

Server-Sent Events (SSE) mode for remote deployments, containers, and web clients:

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

Your MCP client can connect to: http://localhost:8000/sse

---

🔌 MCP Client Configurations

Claude Desktop (claude_desktop_config.json)

Stdio Mode (Recommended):

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

HTTP / SSE Mode:

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

Cursor (~/.cursor/mcp.json)

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

---

🌐 Data Sources & Extraction Architecture

The server fetches data exclusively from the live official web portals of Djinni and DOU:

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

• Endpoint Format: https://djinni.co/salaries/?category={category}&exp={exp}&english_level={level}
• Extraction Method: Live on-demand scraping of Djinni's rolling 30-day platform hiring metrics.
• Extracted Data:
  • Candidate Expectations: 25th–75th percentile salary expectations and calculated median.
  • Company Vacancies: Active job posting salary offer ranges.
  • Market Activity: Real-time counters of active candidates online and open vacancies.
  • Salary Distribution: Full salary bin histogram parsed directly from embedded chart data.

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

• Endpoint Source: Master widget dataset loaded directly by https://jobs.dou.ua/salaries/ (https://s.dou.ua/files/lenta/salary-widget_jun_2026_v3/data/swd-medians.csv).
• Extraction Method: Slices official statistical quartiles ($q1$, $median$, $q3$), respondent sample sizes ($count$), and seniority title levels ($title$).
• Historical Support: Supports querying specific historical survey waves via the as_of_date parameter (e.g. '2025-12', '2026-06'), defaulting to the latest available wave.

---

❓ Why DOU Provider Data May Differ from Website UI Views

When querying DOU via salary-mcp, you might occasionally notice subtle differences between the returned statistics and what is rendered in the interactive UI of jobs.dou.ua/salaries/:

1. Frontend Sample Size Thresholds:
   • On the public website, DOU's charting scripts often apply a minimum sample size threshold (typically $\ge 15-20$ respondents).
   • When a specific experience bracket has fewer respondents (e.g. $11$ respondents for 9 years of experience in Data Science), the website chart suppresses or greys out the bar as "Недостатньо анкет" (Insufficient data).
   • The underlying DOU analytics dataset preserves the exact calculated median for those respondents, which salary-mcp returns accurately.
2. Category Aggregations vs. Specific Title Filtering:
   • Selecting a broad category (e.g. "Data & Analytics" or "Management") on the web interface aggregates all sub-roles together.
   • Specific title queries (e.g. Middle Data Scientist or Junior HR Specialist) match the specific title tier within the dataset.
3. Survey Wave Releases:
   • By default, salary-mcp always selects the most recent official survey wave (e.g. 2026-06). If the website user interface is displaying an earlier wave or a different article, specifying as_of_date ensures identical alignment.

---

🛠️ MCP Tools Reference

get_djinni_salaries

Fetch real-time candidate salary expectations and vacancy offer distributions from Djinni.

• Arguments:
  • role (string, required): Target job role (e.g. "Software Engineer", "QA", "DevOps", "HR").
  • specialization (string, optional): Technology or domain (e.g. "Python", "React", "HR").
  • experience_years (integer, optional): Years of experience (e.g. 0, 2, 5).
  • english_level (string, optional): English proficiency (e.g. "intermediate", "advanced").

get_dou_salaries

Fetch official salary survey benchmarks and percentiles from DOU.

• Arguments:
  • role (string, required): Job role or category (e.g. "Software Engineer", "Data Science").
  • specialization (string, optional): Language or sub-role (e.g. "Python", "Data Scientist").
  • experience_years (integer, optional): Years of professional experience.
  • seniority (string, optional): Seniority tier ("Junior", "Middle", "Senior", "Lead", "Architect").
  • city (string, optional): Location filter (e.g. "Kyiv", "Lviv", "Remote").
  • as_of_date (string, optional): Survey date in YYYY-MM format (e.g. "2025-12", "2026-06"). Defaults to latest.

compare_salaries

Compare salary benchmarks between Djinni and DOU side-by-side with differential analysis.

• Arguments:
  • role (string, required): Target job role.
  • specialization (string, optional): Technology or specialization.
  • experience_years (integer, optional): Years of experience.
  • seniority (string, optional): Seniority level for DOU matching.
  • as_of_date (string, optional): Target survey date for DOU comparison.

list_specializations

List available roles, technologies, seniorities, locations, and historical survey dates.

• Arguments:
  • provider (string, optional): Scope of choices ("all", "djinni", "dou"). Defaults to "all".

---

🛠️ Local Development

# 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

---

📄 License

MIT License. See LICENSE for details.