emovi-mcp

Servidor MCP para la encuesta ESRU-EMOVI 2023 de movilidad social en México.

MCP server for the ESRU-EMOVI 2023 social mobility survey (Mexico).

---

¿Qué es esto?

emovi-mcp permite que asistentes de IA (Claude, ChatGPT, etc.) consulten la encuesta de movilidad social más completa de México mediante lenguaje natural. Expone cómputos estadísticos ponderados, matrices de transición intergeneracional y exploración de variables como herramientas MCP.

Sobre la ESRU-EMOVI 2023

La encuesta ESRU-EMOVI 2023, levantada por el Centro de Estudios Espinosa Yglesias (CEEY), es representativa a nivel nacional sobre movilidad social en México. Cubre 17,843 entrevistados de 25 a 64 años, con factores de expansión que representan ~60 millones de personas.

Bases de datos incluidas:

Base de datos	Descripción	Registros	Variables
entrevistado	Datos del entrevistado principal	17,843	~296
hogar	Roster del hogar	55,477	~56
ingreso_2017	Ingreso imputado 2017 (comparación temporal)	17,665	~2
inclusion_financiera	Módulo de inclusión financiera	5,976	~109

Instalación

# Clonar el repositorio
git clone https://github.com/Lalitronico/emovi-mcp.git
cd emovi-mcp

# Crear entorno virtual
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
.venv\Scripts\activate     # Windows

# Instalar en modo editable con dependencias de desarrollo
pip install -e ".[dev]"

# Opcional: soporte de visualización
pip install -e ".[dev,viz]"

O instalar directamente desde PyPI:

pip install emovi-mcp
# Con soporte de visualización
pip install emovi-mcp[viz]

Prerrequisitos

• Python >= 3.10
• Archivos .dta de la ESRU-EMOVI 2023 (obtener del CEEY)

Configuración

Establecer la variable de entorno EMOVI_DATA_DIR apuntando al directorio con los archivos .dta:

# Linux/Mac
export EMOVI_DATA_DIR="/ruta/a/Esru Emovi 2023/_extracted/3 BASES DE DATOS/Data"

# Windows (PowerShell)
$env:EMOVI_DATA_DIR = "C:\ruta\a\Esru Emovi 2023\_extracted\3 BASES DE DATOS\Data"

# Windows (cmd)
set EMOVI_DATA_DIR=C:\ruta\a\Esru Emovi 2023\_extracted\3 BASES DE DATOS\Data

Uso con Claude Desktop

Agregar lo siguiente al archivo claude_desktop_config.json:

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "emovi-mcp": {
      "command": "C:/ruta/a/emovi-mcp/.venv/Scripts/python.exe",
      "args": ["-m", "emovi_mcp"],
      "env": {
        "EMOVI_DATA_DIR": "C:/ruta/a/3 BASES DE DATOS/Data"
      }
    }
  }
}

En macOS/Linux, reemplazar Scripts/python.exe por bin/python.

Herramientas

El servidor expone 11 herramientas MCP:

Herramienta	Descripción
describe_survey	Panorama de la encuesta: bases de datos, tamaño muestral, diseño, dimensiones
list_variables	Explorar variables por base, sección o palabra clave
variable_detail	Información completa de una variable: etiqueta, valores, sección, base
tabulate	Tabulación cruzada ponderada (fila x columna con factores de expansión)
transition_matrix	Matriz de movilidad intergeneracional con índices formales (Shorrocks, Prais, razón de momios) y errores estándar opcionales vía linealización de Taylor
weighted_stats	Estadísticas descriptivas: media, mediana, desviación estándar, cuantiles (ponderados)
compare_groups	Comparar una variable entre grupos (media, mediana o distribución)
filter_data	Extraer registros con filtros opcionales (máximo 100 filas)
financial_inclusion_summary	Análisis de inclusión financiera: ahorro, crédito, banca, alfabetización, discriminación
income_comparison	Comparación temporal de ingreso 2017 vs 2023 con clasificación por línea de pobreza
visualize_mobility	Generar heatmaps, diagramas Sankey o gráficas de barras para matrices de movilidad (requiere [viz])

Ejemplos de consultas

Una vez conectado, puedes preguntar al asistente de IA cosas como:

• "¿Cuál es la distribución educativa por sexo?" → Usa tabulate(row_var="educ", col_var="sexo")

• "Muéstrame la matriz de movilidad educativa intergeneracional" → Usa transition_matrix(dimension="education")

• "¿Cuál es el ingreso promedio por región?" → Usa weighted_stats(variable="ingc_pc", by="region_14")

• "Compara la movilidad educativa entre hombres y mujeres" → Usa transition_matrix(dimension="education", by="sexo")

• "¿Qué variables hay sobre educación?" → Usa list_variables(search="educ")

Diccionario de variables

El proyecto incluye un diccionario preconstruido con 792 variables extraídas de la documentación oficial del CEEY y los metadatos de los archivos .dta. Soporta búsqueda por nombre, descripción, base de datos y sección.

Para reconstruir el diccionario desde los datos fuente:

python scripts/build_dictionary.py

Esto requiere el archivo Diccionario ESRU EMOVI 2023.xlsx en el directorio de datos.

Ejecutar pruebas

pytest

Las 96 pruebas cubren estadísticas ponderadas, matrices de transición, índices de movilidad, errores estándar por linealización de Taylor, inclusión financiera, comparación temporal de ingreso, visualización y funcionalidad del diccionario de variables, todo con datos sintéticos (no se requieren microdatos reales).

Notas técnicas

• Todas las estadísticas son ponderadas usando la variable de expansión factor (o fac_inc para el módulo de inclusión financiera)
• pyreadstat carga los .dta con apply_value_formats=False para evitar crashes por etiquetas duplicadas de municipios
• padres_edu se construye como max(educp, educm) siguiendo la metodología del .do del CEEY
• Índice de riqueza usa PCA sobre indicadores binarios de activos del hogar (Filmer & Pritchett, 2001), como alternativa al enfoque MCA del CEEY
• Errores estándar usan linealización de Taylor para estimadores de razón bajo muestreo estratificado por conglomerados (UPM/estrato)
• Índices de movilidad: Shorrocks M, probabilidad de escape de Prais, correlación intergeneracional de Pearson r, razón de momios de esquina
• Transporte STDIO: El servidor se comunica por entrada/salida estándar, compatible con Claude Desktop y otros clientes MCP

Estructura del proyecto

emovi-mcp/
├── pyproject.toml
├── README.md
├── LICENSE
├── CONTRIBUTING.md
├── .github/workflows/
│   ├── ci.yml                    # CI: pytest en Python 3.10/3.11/3.12
│   └── publish.yml               # Publicar en PyPI al crear release
├── scripts/
│   └── build_dictionary.py       # Constructor del diccionario
├── src/emovi_mcp/
│   ├── __init__.py
│   ├── __main__.py               # python -m emovi_mcp
│   ├── main.py                   # Punto de entrada del servidor FastMCP
│   ├── config.py                 # Entorno, mapeos, constantes
│   ├── data_loader.py            # Cargador lazy de .dta con caché
│   ├── dictionary.py             # Diccionario de variables (JSON)
│   ├── stats_engine.py           # Matrices de transición, descriptivas
│   ├── data/
│   │   └── dictionary.json       # 792 variables
│   ├── helpers/
│   │   ├── formatting.py         # Formateadores Markdown para salida LLM
│   │   ├── labels.py             # Resolución de etiquetas de valor
│   │   ├── mobility_indices.py   # Shorrocks, Prais, razón de momios
│   │   ├── survey_variance.py    # Linealización de Taylor para SE/CI
│   │   ├── validation.py         # Validación de columnas y filtros
│   │   ├── visualization.py      # Heatmaps, Sankey, gráficas de barras
│   │   └── weights.py            # Media, mediana, cuantil, frecuencia ponderados
│   └── tools/
│       ├── __init__.py            # Registro de herramientas (11 tools)
│       ├── compare.py             # compare_groups
│       ├── describe.py            # describe_survey
│       ├── financial.py           # financial_inclusion_summary
│       ├── mobility.py            # transition_matrix
│       ├── stats.py               # weighted_stats
│       ├── subset.py              # filter_data
│       ├── tabulate.py            # tabulate
│       ├── temporal.py            # income_comparison
│       ├── variables.py           # list_variables, variable_detail
│       └── visualize.py           # visualize_mobility
└── tests/
    ├── conftest.py                # Fixtures compartidos (datos sintéticos)
    ├── test_dictionary.py
    ├── test_financial.py
    ├── test_mobility.py
    ├── test_mobility_indices.py
    ├── test_stats_engine.py
    ├── test_survey_variance.py
    ├── test_temporal.py
    ├── test_visualization.py
    └── test_wealth_index.py

Licencia

MIT

Agradecimientos

Datos de la encuesta: Centro de Estudios Espinosa Yglesias (CEEY) — ESRU-EMOVI 2023.