Salary MCP Server (salary-mcp)

Un servidor Model Context Protocol (MCP) que proporciona a los LLMs acceso directo y programático a datos reales de referencia salarial del mercado TI público de Djinni (djinni.co) y DOU (jobs.dou.ua/salaries/).

⚡ Inicio rápido (paquete publicado en PyPI)

salary-mcp está publicado en PyPI y se puede ejecutar al instante sin necesidad de clonar el repositorio manualmente.

1. Ejecutar a través de Stdio (predeterminado)

Comunicación estándar de entrada/salida para clientes de IA de escritorio (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. Ejecutar a través de HTTP / SSE (servidor remoto)

Modo Server-Sent Events (SSE) para despliegues remotos, contenedores y clientes web:

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

Tu cliente MCP puede conectarse a: http://localhost:8000/sse

Related MCP server: PayHub MCP Server

🔌 Configuraciones de cliente MCP

Claude Desktop (claude_desktop_config.json)

Modo Stdio (recomendado):

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

Modo HTTP / SSE:

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

Cursor (~/.cursor/mcp.json)

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

🌐 Fuentes de datos y arquitectura de extracción

El servidor obtiene datos exclusivamente de los portales web oficiales en vivo de Djinni y DOU:

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

• Formato del endpoint: https://djinni.co/salaries/?category={category}&exp={exp}&english_level={level}

• Método de extracción: scraping en vivo bajo demanda de las métricas móviles de contratación de la plataforma de los últimos 30 días de Djinni.

• Datos extraídos:

  • Expectativas de los candidatos: percentiles 25–75 de las expectativas salariales y mediana calculada.

  • Vacantes de empresas: rangos salariales ofrecidos en ofertas de empleo activas.

  • Actividad del mercado: contadores en tiempo real de candidatos activos en línea y vacantes abiertas.

  • Distribución salarial: histograma completo de intervalos salariales extraído directamente de los datos de los gráficos incrustados.

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

• Fuente del endpoint: conjunto de datos maestro del widget cargado directamente por https://jobs.dou.ua/salaries/ (https://s.dou.ua/files/lenta/salary-widget_jun_2026_v3/data/swd-medians.csv).

• Método de extracción: extrae los cuartiles estadísticos oficiales ($q1$, $median$, $q3$), los tamaños de muestra de encuestados ($count$) y los niveles de título de senioridad ($title$).

• Soporte histórico: permite consultar oleadas históricas específicas de la encuesta mediante el parámetro as_of_date (p. ej. '2025-12', '2026-06'), utilizando por defecto la oleada más reciente disponible.

❓ Por qué los datos del proveedor DOU pueden diferir de las vistas de la interfaz web

Al consultar DOU a través de salary-mcp, es posible que en ocasiones notes diferencias sutiles entre las estadísticas devueltas y lo que se muestra en la interfaz interactiva de jobs.dou.ua/salaries/:

1. Umbrales de tamaño de muestra del frontend:

   • En el sitio web público, los scripts de gráficos de DOU suelen aplicar un umbral mínimo de tamaño de muestra (normalmente $\ge 15-20$ encuestados).

   • Cuando un intervalo de experiencia específico tiene menos encuestados (p. ej. $11$ encuestados para 9 años de experiencia en Data Science), el gráfico del sitio web suprime o atenúa la barra como "Недостатньо анкет" (datos insuficientes).

   • El conjunto de datos analíticos subyacente de DOU conserva la mediana exacta calculada para esos encuestados, y salary-mcp la devuelve con precisión.

2. Agregaciones por categoría frente a filtrado por título específico:

   • Seleccionar una categoría amplia (p. ej. "Data & Analytics" o "Management") en la interfaz web agrega todos los subroles juntos.

   • Las consultas por título específico (p. ej. Middle Data Scientist o Junior HR Specialist) coinciden con el nivel de título específico dentro del conjunto de datos.

3. Publicación de oleadas de encuestas:

   • De forma predeterminada, salary-mcp siempre selecciona la oleada oficial de encuesta más reciente (p. ej. 2026-06). Si la interfaz de usuario del sitio web muestra una oleada anterior o un artículo distinto, especificar as_of_date garantiza una alineación idéntica.

🛠️ Referencia de herramientas MCP

get_djinni_salaries

Obtiene expectativas salariales de candidatos en tiempo real y distribuciones de ofertas de vacantes de Djinni.

• Argumentos:

  • role (string, required): Rol de trabajo objetivo (p. ej. "Software Engineer", "QA", "DevOps", "HR").

  • specialization (string, optional): Tecnología o dominio (p. ej. "Python", "React", "HR").

  • experience_years (integer, optional): Años de experiencia (p. ej. 0, 2, 5).

  • english_level (string, optional): Nivel de inglés (p. ej. "intermediate", "advanced").

get_dou_salaries

Obtiene estadísticas oficiales y percentiles de las encuestas salariales de DOU.

• Argumentos:

  • role (string, required): Rol de trabajo o categoría (p. ej. "Software Engineer", "Data Science").

  • specialization (string, optional): Lenguaje o subrol (p. ej. "Python", "Data Scientist").

  • experience_years (integer, optional): Años de experiencia profesional.

  • seniority (string, optional): Nivel de senioridad ("Junior", "Middle", "Senior", "Lead", "Architect").

  • city (string, optional): Filtro de ubicación (p. ej. "Kyiv", "Lviv", "Remote").

  • as_of_date (string, optional): Fecha de la encuesta en formato YYYY-MM (p. ej. "2025-12", "2026-06"). Se usa la más reciente por defecto.

compare_salaries

Compara estadísticas salariales entre Djinni y DOU lado a lado con análisis diferencial.

• Argumentos:

  • role (string, required): Rol de trabajo objetivo.

  • specialization (string, optional): Tecnología o especialización.

  • experience_years (integer, optional): Años de experiencia.

  • seniority (string, optional): Nivel de senioridad para la coincidencia con DOU.

  • as_of_date (string, optional): Fecha de encuesta objetivo para la comparación con DOU.

list_specializations

Enumera roles, tecnologías, niveles de senioridad, ubicaciones y fechas históricas de encuestas disponibles.

• Argumentos:

  • provider (string, optional): Alcance de las opciones ("all", "djinni", "dou"). Por defecto "all".

🛠️ Desarrollo local

# 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

📄 Licencia

Licencia MIT. Consulta LICENSE para obtener más detalles.