Habitica MCP Server 🧙‍♂️⚔️

Servidor Model Context Protocol (MCP) completo para Habitica, desarrollado con Python y FastMCP.

Permite a cualquier modelo de Inteligencia Artificial (Claude Desktop, Gemini CLI, Antigravity, Cursor) interactuar de forma nativa con todo el ecosistema de Habitica: autenticación directa sin tokens manuales, gestión de tareas, equipos y misiones, chat, personaje, inventario, mascotas y desafíos.

🌟 Características Principales

• 🔑 Login sin Tokens Manuales: Puedes iniciar sesión directamente con tu usuario/email y contraseña usando la ventana interactiva (login_window.py) o la herramienta MCP habitica_login. Las credenciales se conservan de forma segura y local en .habitica_session.json (ignorado por Git).

• 👥 Gestión Integral de Equipos (Party & Guilds): Consulta detalles, roster con niveles y clases, auditoría de inactividad (get_party_activity_summary), reclutamiento y expulsión de miembros inactivos (remove_group_member).

• 🐉 Misiones de Equipo (Quests): Convoca misiones con pergaminos, acéptalas, recházalas o cancélalas.

• 💬 Chat Integrado: Lee los chats de equipo/gremios en tiempo real, envía mensajes y da "likes".

• ⚔️ Gestión de Tareas y Hábitos: CRUD completo de hábitos (+/-), diarias, to-dos y recompensas con dificultad configurable. ¡Puntúa tareas (score_task) para ganar oro, EXP y golpear al jefe!

• 🧙‍♂️ Personaje y Progresión: Consulta vida, maná, oro, racha y clase. Lanza hechizos, duerme en la Posada (pausar daño diario) y asigna puntos de atributo ganados al subir nivel.

• 🎒 Inventario y Mercado: Equipa armaduras/armas de combate o de disfraz (costume), compra pociones y pergaminos.

• 🐾 Mascotas y Monturas: Eclosiona huevos con pociones y alimenta a tus criaturas.

• 🏷️ Etiquetas (Tags): Crea, edita y asocia tags a tareas.

• 🏆 Desafíos (Challenges): Crea retos para tu party con premios en gemas, agrega tareas al reto, únete, abandona y corona al ganador (select_challenge_winner).

Related MCP server: eighty MCP

📋 Requisitos Previos

• Python 3.10 o superior (probado en Python 3.10 - 3.14).

• Gestor de paquetes pip o uv.

🚀 Instalación Paso a Paso

1. Clonar el Repositorio

git clone https://github.com/TU_USUARIO/habitica-mcp.git
cd habitica-mcp

2. Crear un Entorno Virtual (Opcional pero recomendado)

# Con Python estándar
python -m venv .venv
# En Windows:
.venv\Scripts\activate
# En Linux/macOS:
source .venv/bin/activate

3. Instalar Dependencias

Instala el paquete en modo editable con pip:

pip install -e .

(O si usas uv: uv sync)

🔐 Autenticación (Cómo Iniciar Sesión)

Dispones de dos opciones:

Opción A: Interfaz Gráfica o Consola (Recomendada)

No necesitas copiar ni pegar manualmente tu User ID ni tu API Token. Simplemente ejecuta:

• Ventana visual (GUI nativa):

  python login_window.py

• En consola / terminal:

  python login.py

Ingresa tu usuario (o correo) y contraseña. El script se conectará a Habitica, obtendrá tus identificadores de sesión y los guardará localmente en .habitica_session.json.

Opción B: Variables de Entorno (.env)

Si prefieres usar tus API Tokens directamente:

1. Copia .env.example a .env:

   cp .env.example .env

2. Completa tus credenciales (disponibles en Habitica en Configuración > API):

   HABITICA_USER_ID=tu-user-id-uuid
   HABITICA_API_TOKEN=tu-api-token
   HABITICA_CLIENT_NAME=HabiticaMCP

⚙️ Configuración en Clientes MCP

En Claude Desktop (claude_desktop_config.json)

Añade lo siguiente a tu archivo de configuración de Claude Desktop:

{
  "mcpServers": {
    "habitica": {
      "command": "python",
      "args": [
        "-m",
        "habitica.server"
      ],
      "cwd": "/ruta/absoluta/a/habitica-mcp"
    }
  }
}

(En Windows usa doble barra invertida en la ruta, ej: D:\\proyectos\\habitica-mcp).

En Gemini CLI / Antigravity (mcp_config.json)

{
  "mcpServers": {
    "habitica": {
      "command": "python",
      "args": [
        "-m",
        "habitica.server"
      ],
      "cwd": "D:\\PERSONAL\\PRACTICAS\\PROGRAMACIÓN\\MCP-ANTIGRAVITY\\habitica-mcp"
    }
  }
}

🛠️ Catálogo Completo de Herramientas (59 Tools)

• habitica_login(username_or_email, password): Login directo con usuario y contraseña.

• habitica_auth_status(): Estado actual de la conexión.

• habitica_logout(): Cierra sesión y elimina credenciales locales.

• get_groups(group_types): Lista grupos del usuario.

• get_group_details(group_id): Detalles del equipo/gremio.

• get_group_members(group_id, include_all_public_fields): Lista completa de integrantes con estadísticas.

• get_party_activity_summary(group_id): Resumen de actividad y tiempo de inactividad de los miembros.

• invite_to_group(group_id, uuids, emails): Invitar miembros por ID o correo.

• remove_group_member(member_id, group_id, message): Expulsar miembros (solo líder).

• create_group(name, group_type, privacy, description): Crear gremio o equipo.

• update_group(group_id, name, description, leader_message): Actualizar ajustes de grupo.

• join_group(group_id): Unirse a un grupo.

• leave_group(group_id, keep_challenges): Salir de un grupo.

• reject_group_invite(group_id): Rechazar invitación.

• quest_invite(quest_key): Iniciar misión con pergamino.

• quest_accept(): Aceptar misión activa.

• quest_reject(): Rechazar misión.

• quest_abort(): Cancelar misión en curso (líder).

• quest_leave(): Abandonar misión individualmente.

• get_group_chat(group_id): Leer últimos mensajes.

• send_group_chat(message, group_id): Publicar en el chat.

• like_chat_message(chat_id, group_id): Dar like a un mensaje.

• mark_chat_seen(group_id): Marcar chat como leído.

• get_tasks(task_type): Listar hábitos, diarias, to-dos o recompensas.

• get_task(task_id): Detalles de una tarea específica.

• create_task(text, task_type, notes, priority, up, down, due_date, tags): Crear nueva tarea.

• update_task(task_id, text, notes, priority): Modificar tarea.

• delete_task(task_id): Borrar tarea.

• score_task(task_id, direction): Puntuar tarea (up/down).

• unlink_all_challenge_tasks(keep): Desvincular tareas de retos.

• get_user_profile(user_fields): Estadísticas completas (HP, MP, EXP, GP, nivel, clase).

• get_anonymized_profile(): Datos públicos del personaje.

• toggle_sleep(): Pausar/reanudar daño durmiendo en la Posada.

• cast_spell(spell_id, target_id): Lanzar habilidades de clase.

• allocate_stat_point(stat): Asignar puntos a atributos (str, con, int, per).

• trigger_cron(): Procesar cambio de día manualmente.

• equip_item(item_key, slot_type): Equipar equipo de combate (equipped) o cosmético (costume).

• buy_item(item_key): Comprar pociones o equipo en la tienda con oro.

• get_buy_inventory(): Catálogo de ítems en venta.

• hatch_pet(egg, hatching_potion): Eclosionar huevos con pociones.

• feed_pet(pet, food): Alimentar mascotas para convertirlas en monturas.

• get_tags(): Listar etiquetas.

• create_tag(name): Crear etiqueta.

• update_tag(tag_id, name): Renombrar etiqueta.

• delete_tag(tag_id): Eliminar etiqueta.

• tag_task(task_id, tag_id): Asignar etiqueta a tarea.

• untag_task(task_id, tag_id): Quitar etiqueta.

• get_my_challenges(page): Desafíos activos o disponibles.

• get_party_challenges(group_id): Desafíos de tu equipo.

• get_challenge_details(challenge_id): Ver reglas y participantes.

• get_challenge_tasks(challenge_id): Tareas asignadas al reto.

• create_challenge(name, short_name, description, summary, group_id, prize): Crear nuevo desafío.

• add_task_to_challenge(challenge_id, text, task_type, notes, priority, up, down): Agregar tareas al reto.

• update_challenge(challenge_id, name, description, summary): Editar desafío.

• clone_challenge(challenge_id): Duplicar reto existente.

• delete_challenge(challenge_id): Borrar reto y reembolsar premio.

• join_challenge(challenge_id): Unirse al desafío.

• leave_challenge(challenge_id, keep): Salir del reto.

• select_challenge_winner(challenge_id, winner_id): Elegir ganador y transferir premio.

🔒 Seguridad y Privacidad

• Este repositorio no almacena contraseñas ni tokens.

• El archivo de sesión .habitica_session.json y los archivos .env están protegidos e incluidos en el .gitignore.

• Toda la comunicación con los servidores de Habitica se realiza exclusivamente mediante HTTPS (https://habitica.com/api/v3).

📄 Licencia

Distribuido bajo la Licencia MIT. Consulta el archivo LICENSE para más detalles.