MCP Personal Assistant Agent

MCP Personal Assistant Agent

Un agente de asistente personal versátil construido con el Protocolo de Contexto de Modelos (MCP) que ayuda con calendario, tareas, correos electrónicos y más.

Resumen

Este proyecto es un servidor del Protocolo de Contexto de Modelos (MCP) que proporciona un conjunto de herramientas para un agente asistente personal. Puede integrarse con clientes MCP como Claude para Desktop para dar a los asistentes de IA la capacidad de:

• Gestionar eventos de calendario
• Realizar seguimiento de tareas y pendientes
• Leer y enviar correos electrónicos
• Buscar en la web y recuperar información
• Controlar dispositivos de hogar inteligente

Requisitos

⚠️ IMPORTANTE: Se requiere Python 3.10 o superior para el SDK de MCP. El servidor no funcionará con versiones anteriores de Python.

• Python 3.10+
• MCP SDK 1.2.0+
• Paquetes de Python requeridos (ver requirements.txt)

Instalación

1. Clona el repositorio:

git clone https://github.com/yourusername/mcp-pa-ai-agent.git
cd mcp-pa-ai-agent

2. Asegúrate de tener Python 3.10+:

python --version

3. Si el Python de tu sistema es anterior a 3.10, configura un entorno compatible:

# Using conda
conda create -n mcp-env python=3.10
conda activate mcp-env

# OR using venv (if Python 3.10+ is installed elsewhere)
python3.10 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

4. Instala las dependencias:

pip install -r requirements.txt

5. Configura las variables de entorno copiando el archivo de ejemplo:

cp .env.example .env

6. Edita el archivo .env con tus credenciales de API y configuración.

Ejecutar el Servidor

Inicia el servidor MCP con:

python mcp_server.py

El servidor se iniciará y escuchará conexiones de clientes MCP.

Conexión con Claude para Desktop

1. Instala Claude para Desktop

2. Configura Claude para Desktop para usar este servidor MCP editando el archivo de configuración en:

   • MacOS/Linux: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

3. Agrega la siguiente configuración:

{
  "mcpServers": {
    "personal-assistant": {
      "command": "/path/to/python",
      "args": [
        "/absolute/path/to/mcp-pa-ai-agent/mcp_server.py"
      ]
    }
  }
}

Si estás usando un entorno virtual, asegúrate de apuntar al ejecutable de Python en ese entorno.

4. Reinicia Claude para Desktop

Herramientas Disponibles

Calendario

• get_events: Recuperar próximos eventos de calendario
• create_event: Programar un nuevo evento de calendario

Tareas

• list_tasks: Ver todas las tareas o filtrar por estado
• add_task: Crear una nueva tarea
• update_task_status: Marcar tareas como pendientes, en progreso o completadas

Correo Electrónico

• get_emails: Listar correos electrónicos recientes de tu bandeja de entrada
• read_email: Ver el contenido completo de un correo electrónico específico
• send_email: Redactar y enviar un nuevo correo electrónico

Conocimiento

• web_search: Buscar en la web información
• get_weather: Obtener información meteorológica actual
• get_news: Recuperar artículos de noticias recientes

Hogar Inteligente

• list_devices: Ver todos los dispositivos de hogar inteligente
• control_device: Controlar dispositivos de hogar inteligente (luces, termostatos, etc.)
• get_device_state: Obtener información detallada sobre el estado actual de un dispositivo

Configuración

El servidor requiere varias claves de API y credenciales para acceder a diferentes servicios:

• API de Google: Para funcionalidad de calendario y correo electrónico (credenciales OAuth2)
• API meteorológica: Para información del clima
• API de noticias: Para recuperación de noticias
• Home Assistant: Para control de hogar inteligente

Consulta el archivo .env.example para todas las opciones configurables.

Solución de Problemas

Problemas de Versión de Python

Si ves un error como:

Error: Python 3.10 or higher is required for the MCP server.

Necesitas actualizar tu versión de Python o usar un entorno virtual con Python 3.10+.

Problemas de Instalación del SDK de MCP

Si encuentras problemas al instalar el SDK de MCP:

ERROR: Could not find a version that satisfies the requirement mcp>=1.2.0

Asegúrate de estar usando Python 3.10+ y que pip esté actualizado:

pip install --upgrade pip

Desarrollo

Para agregar nueva funcionalidad al servidor, puedes:

1. Crear un nuevo módulo en el directorio modules/
2. Implementar funciones con el decorador @mcp.tool()
3. Importar tu módulo en mcp_server.py

Licencia

MIT

Contribuciones

¡Las contribuciones son bienvenidas! No dudes en enviar una Solicitud de Extracción (Pull Request).