MCP Chamba

English summary. MCP Chamba is a local Model Context Protocol server that turns Claude (Claude Code or Claude Desktop) into a job-search assistant. It pulls openings from public job-board APIs (Get on Board, Remotive, RemoteOK, Jobicy, Himalayas, Arbeitnow) and company boards (Greenhouse, Lever, Ashby), scores each one 0–100 against your profile with explainable reasons, generates an ATS-friendly CV and cover letter tailored to the offer (PDF), refuses any figure that is not in your profile, and tracks every application and follow-up in a local SQLite database. Your data never leaves your machine. The code and docs are in Spanish; it is tuned for candidates in Colombia / LATAM looking for remote work.

Chamba es "trabajo" en buena parte de Latinoamérica. Este servidor MCP le da a Claude las herramientas para ayudarte a conseguirla: buscar → calificar → adaptar la hoja de vida y la carta → postularte tú → hacer seguimiento.

Contenido

• Qué hace

• Herramientas

• Arquitectura

• Requisitos

• Instalación

• Configuración

• Conectarlo a Claude

• Uso: el flujo típico

• Cómo se califica una oferta

• Privacidad

• Estructura del proyecto

• Desarrollo y contribuciones

• Limitaciones conocidas

• Licencia

Related MCP server: JobPilot MCP

Qué hace

• Busca ofertas en portales con API pública y en los portales de empleo de las empresas que sigues, en paralelo, y guarda lo visto para no repetir consultas (cada fuente se consulta como máximo cada 6 horas por búsqueda).

• Califica cada oferta de 0 a 100 contra tu perfil y explica por qué: qué tecnologías coinciden, cuáles se parecen a las tuyas, qué te falta, si aceptan gente desde Colombia, si pide más años de los que tienes o si paga menos de lo que esperas.

• Genera la hoja de vida en PDF adaptada a la oferta: una columna, texto real y sin tablas (la leen bien los filtros ATS), con primero los logros que más se parecen a lo que piden, en español o inglés según el idioma de la oferta.

• Guarda la carta de presentación (Markdown + PDF con el mismo encabezado de la hoja de vida).

• No deja inventar: si el titular, el resumen o la carta mencionan una cifra que no aparece en tu perfil (250.000 usuarios, 95 %…), la herramienta lo rechaza.

• Lleva el seguimiento de cada postulación (guardada → preparada → postulada → entrevista → prueba técnica → oferta → aceptada / rechazada / descartada) y te avisa cuándo toca escribirle al reclutador.

• Prepara entrevistas con tus historias STAR, lo que coincide y lo que falta, y el rango salarial de ofertas parecidas.

• Tú envías cada postulación. El servidor nunca postula por ti: prepara los documentos y te da el enlace.

Herramientas

Además expone dos guías (prompts MCP), que en Claude Code aparecen al escribir /:

• rutina_diaria: seguimientos vencidos, búsquedas del día (las de objetivo.busquedas en tu perfil) y un top 10 para decidir qué preparar.

• postular: prepara una postulación completa (hoja de vida, carta, qué te falta y el enlace).

Arquitectura

            Claude Code / Claude Desktop
                       │  MCP por stdio
                       ▼
 ┌──────────────────── empleo/servidor.py ─────────────────────┐
 │ 13 herramientas + 2 guías · reglas anti-invención de cifras │
 └──┬──────────────┬───────────────┬──────────────┬────────────┘
    │              │               │              │
    ▼              ▼               ▼              ▼
 fuentes.py     ajuste.py       cv.py          base.py
 APIs públicas  puntaje 0-100   Jinja2 +       SQLite local
 de empleo      y razones       WeasyPrint     (ofertas, postulaciones,
 (httpx async)  (vocabulario)   → PDF          historial, consultas)
    │              │               │
    │              ▼               ▼
    │          perfil.py ◀── perfil/perfil.yaml (tuyo, fuera de git)
    ▼
 Get on Board · Remotive · RemoteOK · Jobicy · Himalayas · Arbeitnow
 Greenhouse · Lever · Ashby (portales de empresas)

Claude escribe los textos (titular, resumen, carta); el servidor aporta los hechos, valida las cifras y produce los documentos. No hace falta ninguna clave de API.

Requisitos

• Python 3.12+ y uv (gestiona el entorno y las dependencias).

• Pango, que WeasyPrint necesita para generar los PDF:

  • Debian / Ubuntu: sudo apt install libpango-1.0-0 libpangoft2-1.0-0

  • Fedora: sudo dnf install pango

  • Arch: sudo pacman -S pango

  • macOS: brew install pango

  • Windows: ver la guía de WeasyPrint.

• Recomendado: la fuente Noto Sans (fonts-noto / noto-fonts), que usa la plantilla.

• Claude Code o Claude Desktop.

Instalación

git clone https://github.com/yrey420/MCP-CHAMBA.git
cd MCP-CHAMBA
uv sync                 # crea .venv e instala dependencias
uv run pytest           # opcional: 39 pruebas, sin salir a internet

Configuración

1. Tu perfil

Todo lo que el asistente sabe de ti sale de un único archivo YAML. Parte del ejemplo (un perfil ficticio, "Alex Ejemplo"):

cp perfil/perfil.example.yaml perfil/perfil.yaml

y edítalo con tus datos. perfil/perfil.yaml está en .gitignore: nunca se sube. Si no existe, el servidor arranca con el perfil de ejemplo y lo avisa en ver_perfil y al generar documentos.

Secciones principales (el ejemplo trae comentarios en cada una):

2. Empresas que sigues (opcional)

No hace falta crearlo: seguir_empresa escribe perfil/empresas.yaml (también ignorado por git). El formato está en perfil/empresas.example.yaml.

3. Variables de entorno (opcionales)

Por defecto todo vive dentro de la carpeta del proyecto. Puedes guardar tus datos en otro lugar:

No se necesitan claves ni tokens: todas las fuentes son públicas.

Conectarlo a Claude

Claude Code

claude mcp add --scope user empleo -- uv run --directory /ruta/absoluta/a/MCP-CHAMBA empleo-mcp

Con tus datos fuera del repositorio:

claude mcp add --scope user empleo \
  -e EMPLEO_PERFIL="$HOME/.config/chamba/perfil.yaml" \
  -e EMPLEO_BASE="$HOME/.local/share/chamba/empleo.db" \
  -e EMPLEO_SALIDA="$HOME/Documentos/chamba" \
  -- uv run --directory /ruta/absoluta/a/MCP-CHAMBA empleo-mcp

Comprueba que quedó conectado con claude mcp list (o /mcp dentro de Claude Code).

Claude Desktop

Edita claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\, Linux: ~/.config/Claude/) y reinicia la aplicación:

{
  "mcpServers": {
    "empleo": {
      "command": "uv",
      "args": ["run", "--directory", "/ruta/absoluta/a/MCP-CHAMBA", "empleo-mcp"],
      "env": {
        "EMPLEO_PERFIL": "/ruta/absoluta/a/perfil.yaml"
      }
    }
  }
}

Si Claude Desktop no encuentra uv, pon la ruta completa (which uv) en command.

El ejecutable también se llama mcp-chamba; empleo-mcp y mcp-chamba son equivalentes.

Uso: el flujo típico

Le hablas a Claude en lenguaje natural; él decide qué herramienta usar.

buscar_ofertas ─▶ ver_oferta ─▶ generar_cv_para_oferta ─▶ (tú envías) ─▶ actualizar_postulacion
                                  + guardar_carta                         └─▶ ver_postulaciones

1. Buscar. "Búscame ofertas de python django remotas" → buscar_ofertas devuelve el top con puntaje, empresa, si aceptan Colombia, salario y razones.

2. Revisar. "Muéstrame la de Acme" → ver_oferta con lo que coincide y lo que falta.

3. Preparar. "Prepárame la postulación" (o la guía /postular) → Claude lee ver_perfil, escribe un titular y resumen adaptados solo con hechos de tu perfil, genera la hoja de vida con generar_cv_para_oferta y la carta con guardar_carta. Quedan en salida/postulaciones/<fecha>-<empresa>-<cargo>/ junto con oferta.md.

4. Postular (tú). Abres el enlace, revisas los PDF y envías.

5. Registrar. "Ya me postulé" → actualizar_postulacion con estado postulada; el seguimiento queda programado para dentro de 7 días.

6. Seguimiento. "¿Cómo voy?" → ver_postulaciones muestra el tablero y los seguimientos vencidos; Claude puede redactar el mensaje al reclutador.

7. Entrevista. "Prepárame la entrevista con Acme" → preparar_entrevista: preguntas probables, respuestas con tus historias STAR, cómo cubrir lo que falta y qué cifra pedir.

Otros ejemplos:

• "¿Cuánto están pagando por backend con Django?" → rango_salarial

• "Sigue el portal de Acme en Greenhouse, slug acme" → seguir_empresa

• "Te pego una oferta de LinkedIn, agrégala" → agregar_oferta

• "Esa no, descártala: solo aceptan gente en EE. UU." → descartar_oferta

Sin Claude, también puedes generar la hoja de vida general:

uv run python generar_cv.py --idioma es
uv run python generar_cv.py --idioma en --etiquetas backend,integraciones,ia --salida salida/cv-ia.pdf

Cómo se califica una oferta

El puntaje (0–100) suma cuatro partes y resta lo que pesa en contra. Lo importante son las razones, que acompañan cada resultado:

Al cambiar las reglas, sube ajuste.VERSION: las ofertas guardadas se vuelven a calificar solas.

Privacidad

• Todo es local. Tu perfil, la base SQLite, las hojas de vida y las cartas viven en tu máquina. No hay telemetría ni servidores propios.

• Lo único que sale a internet son consultas de lectura a las APIs públicas de los portales (con el término de búsqueda), identificadas con un User-Agent propio y limitadas a una por fuente y búsqueda cada 6 horas.

• Lo que ves en Claude sí pasa por Claude: lo que devuelven las herramientas (incluido tu perfil) llega al modelo como cualquier otra conversación.

• Nada personal entra en git: .gitignore excluye perfil/ (salvo los *.example.yaml), datos/, salida/, *.db, *.pdf y .env. Las pruebas usan el perfil ficticio y carpetas temporales.

• Usa reglas_para_el_asistente para lo que no debe decirse nunca (clientes bajo acuerdo de confidencialidad, temas personales, etc.).

Estructura del proyecto

MCP-CHAMBA/
├── empleo/
│   ├── servidor.py        # servidor MCP: herramientas, guías e instrucciones
│   ├── fuentes.py         # conectores a portales de empleo
│   ├── ajuste.py          # puntaje 0-100 y razones
│   ├── vocabulario.py     # tecnologías y cómo reconocerlas
│   ├── perfil.py          # carga y resumen del perfil
│   ├── cv.py              # hoja de vida y carta en PDF
│   ├── base.py            # SQLite: ofertas, postulaciones, historial
│   └── rutas.py           # rutas y variables de entorno
├── perfil/
│   ├── perfil.example.yaml    # perfil ficticio: cópialo a perfil.yaml
│   └── empresas.example.yaml  # formato de las empresas seguidas
├── plantillas/
│   ├── cv.html            # plantilla Jinja2 de la hoja de vida
│   ├── carta.html         # plantilla de la carta
│   └── cv.css             # estilos (una columna, apta para ATS)
├── tests/                 # pytest, sin red (httpx.MockTransport)
├── generar_cv.py          # CLI: hoja de vida general en PDF
├── pyproject.toml
├── uv.lock
└── LICENSE

Se crean al usarlo (y no se suben): perfil/perfil.yaml, perfil/empresas.yaml, datos/empleo.db y salida/.

Desarrollo y contribuciones

¡Bienvenidas! Issues y pull requests en español o inglés.

uv sync
uv run pytest            # pruebas
uv run ruff check .      # lint
uv run ruff format .     # formato

Pautas:

• Nueva fuente de ofertas: una función async en empleo/fuentes.py que reciba el cliente httpx y la consulta y devuelva list[Oferta]; regístrala en POR_BUSQUEDA (o en POR_EMPRESA si es un ATS por empresa) y agrega una prueba con una respuesta de ejemplo en tests/test_fuentes.py. Solo APIs públicas que permitan la consulta; nada de scraping que viole términos de uso.

• Nueva tecnología: agrégala a TECNOLOGIAS en empleo/vocabulario.py (y, si aplica, a PARIENTES o ETIQUETA_DE).

• Cambios en el puntaje: acompáñalos de pruebas en tests/test_ajuste.py y sube ajuste.VERSION.

• Nunca subas datos reales en pruebas, ejemplos o capturas: usa el perfil ficticio.

Limitaciones conocidas

• Pensado para buscar desde Colombia / LATAM: las reglas de ubicación (GEO_OK, GEO_RESTRINGIDA en empleo/ajuste.py) y la conversión a pesos lo reflejan. Para otro país, ajusta esas expresiones.

• Las tasas de cambio (ajuste.USD_POR) son aproximadas y fijas: sirven para comparar rangos, no para cuentas exactas.

• LinkedIn, Computrabajo y elempleo no tienen API pública: esas ofertas se agregan pegando el texto (agregar_oferta).

• La detección de tecnologías es por expresiones regulares: puede tener falsos positivos o negativos en ofertas ambiguas.

Licencia

MIT © 2026 Yeison Rey