MCP Personal Assistant Agent

Um assistente pessoal de IA versátil para gerenciar sua agenda, tarefas, e-mails, pesquisas na web e casa inteligente.

GitHub
23
Experimente este MCPPatrocinado

Documentação

MCP Personal Assistant Agent

Um agente de IA assistente pessoal versátil construído com o Model Context Protocol (MCP) que ajuda com calendário, tarefas, e-mails e muito mais.

Visão Geral

Este projeto é um servidor Model Context Protocol (MCP) que fornece um conjunto de ferramentas para um agente assistente pessoal. Ele pode ser integrado a clientes MCP como o Claude for Desktop para dar aos assistentes de IA a capacidade de:

  • Gerenciar eventos de calendário
  • Acompanhar tarefas e afazeres
  • Ler e enviar e-mails
  • Pesquisar na web e recuperar informações
  • Controlar dispositivos de casa inteligente

Requisitos

⚠️ IMPORTANTE: Python 3.10 ou superior é necessário para o MCP SDK. O servidor não funcionará com versões anteriores do Python.

  • Python 3.10+
  • MCP SDK 1.2.0+
  • Pacotes Python necessários (veja requirements.txt)

Instalação

  1. Clone o repositório:
git clone https://github.com/yourusername/mcp-pa-ai-agent.git
cd mcp-pa-ai-agent
  1. Certifique-se de ter Python 3.10+:
python --version
  1. Se o Python do seu sistema for anterior ao 3.10, configure um ambiente compatível:
# 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
  1. Instale as dependências:
pip install -r requirements.txt
  1. Configure as variáveis de ambiente copiando o arquivo de exemplo:
cp .env.example .env
  1. Edite o arquivo .env com suas credenciais e configurações de API.

Executando o Servidor

Inicie o servidor MCP com:

python mcp_server.py

O servidor iniciará e aguardará conexões de clientes MCP.

Conectando ao Claude for Desktop

  1. Instale o Claude for Desktop

  2. Configure o Claude for Desktop para usar este servidor MCP editando o arquivo de configuração em:

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

  3. Adicione a seguinte configuração:

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

Se você estiver usando um ambiente virtual, certifique-se de apontar para o executável Python nesse ambiente.

  1. Reinicie o Claude for Desktop

Ferramentas Disponíveis

Calendário

  • get_events: Recuperar eventos de calendário futuros
  • create_event: Agendar um novo evento de calendário

Tarefas

  • list_tasks: Visualizar todas as tarefas ou filtrar por status
  • add_task: Criar uma nova tarefa
  • update_task_status: Marcar tarefas como pendentes, em andamento ou concluídas

E-mail

  • get_emails: Listar e-mails recentes da sua caixa de entrada
  • read_email: Visualizar o conteúdo completo de um e-mail específico
  • send_email: Redigir e enviar um novo e-mail

Conhecimento

  • web_search: Pesquisar na web por informações
  • get_weather: Obter informações meteorológicas atuais
  • get_news: Recuperar artigos de notícias mais recentes

Casa Inteligente

  • list_devices: Visualizar todos os dispositivos de casa inteligente
  • control_device: Controlar dispositivos de casa inteligente (luzes, termostatos, etc.)
  • get_device_state: Obter informações detalhadas sobre o estado atual de um dispositivo

Configuração

O servidor requer várias chaves de API e credenciais para acessar diferentes serviços:

  • Google API: Para funcionalidade de calendário e e-mail (credenciais OAuth2)
  • Weather API: Para informações meteorológicas
  • News API: Para recuperação de notícias
  • Home Assistant: Para controle de casa inteligente

Consulte o arquivo .env.example para todas as opções configuráveis.

Solução de Problemas

Problemas de Versão do Python

Se você vir um erro como:

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

Você precisa atualizar sua versão do Python ou usar um ambiente virtual com Python 3.10+.

Problemas de Instalação do MCP SDK

Se você encontrar problemas ao instalar o MCP SDK:

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

Certifique-se de estar usando Python 3.10+ e que o pip esteja atualizado:

pip install --upgrade pip

Desenvolvimento

Para adicionar novas funcionalidades ao servidor, você pode:

  1. Criar um novo módulo no diretório modules/
  2. Implementar funções com o decorador @mcp.tool()
  3. Importar seu módulo em mcp_server.py

Licença

MIT

Contribuição

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request.