Servidor MCP para Google Fit (Google Takeout)

Este projeto contém um Servidor MCP (Model Context Protocol) modular desenvolvido em Python com a biblioteca FastMCP. O servidor descompacta, lê, filtra e analisa automaticamente as pastas exportadas do Google Fit (extraídas do Google Takeout em Português) colocadas na pasta ./data.

---

Estrutura Modular do Projeto

cli_project/
├── data/                                # Ignorada no .gitignore (dados privados)
│   ├── Atividades/                      # Ficheiros de registo de treinos e sessões
│   ├── Métricas de atividade diária/   # Ficheiros de passos, calorias e minutos ativos
│   ├── Todas as sessões/               # Histórico completo de sessões de exercício
│   └── Todos os dados/                  # Ficheiros JSON derived_com.google.*
├── src/                                 # Pacote Python com arquitetura modular
│   ├── models/                          # Schemas e estruturas de dados Pydantic
│   │   └── fitness_schemas.py
│   ├── parsers/                         # Parsers de ficheiros (ZIP, CSV, JSON)
│   │   ├── zip_extractor.py
│   │   ├── csv_parser.py
│   │   └── json_parser.py
│   ├── services/                        # Regras de negócio e agregação de dados
│   │   └── fitness_service.py
│   ├── server/                          # Componentes registados no FastMCP
│   │   ├── tools.py                     # Definição das Ferramentas (@mcp.tool)
│   │   ├── resources.py                 # Definição dos Recursos (@mcp.resource)
│   │   └── prompts.py                   # Definição dos Prompts (@mcp.prompt)
│   └── app.py                           # Inicialização e configuração do FastMCP
├── mcp_server.py                        # Ponto de entrada leve do Servidor MCP
├── pyproject.toml                       # Configuração e dependências
├── .gitignore                           # Proteção dos seus dados privados (data/)
└── README.md                            # Documentação de integração

---

Instalação

1. Criar e ativar o ambiente virtual:

   uv venv
   .venv\Scripts\activate
   uv pip install -e .
   

---

Como Integrar o Servidor MCP em Qualquer IA

Adicione o servidor no ficheiro de configuração MCP do seu cliente de IA (mcp_config.json ou claude_desktop_config.json):

{
  "mcpServers": {
    "google-fit-server": {
      "command": "uv",
      "args": [
        "run",
        "mcp_server.py"
      ]
    }
  }
}

---

Como Testar no MCP Inspector

Para testar o servidor e inspecionar as pastas do Google Fit no ambiente gráfico de desenvolvimento:

uv run mcp dev mcp_server.py

---

Guia Detalhado de Utilização dos Componentes MCP

1. Ferramentas (Tools)

As ferramentas permitem que os assistentes de IA executem funções de consulta e manutenção de dados.

clean_empty_data_files

• Descrição: Analisa e deteta ficheiros JSON ou CSV na pasta ./data que contêm zero pontos de dados ou apenas valores vazios "".
• Parâmetros:
  • dry_run (boolean, opcional, padrão: true): Se true, apenas lista os ficheiros vazios sem apagar. Se false, elimina fisicamente os ficheiros vazios do disco.
• Exemplos de Valores e Chamadas:
  • Simulação (listar sem apagar): clean_empty_data_files(dry_run=true)
  • Eliminação física: clean_empty_data_files(dry_run=false)

scan_google_fit_data

• Descrição: Percorre a pasta ./data, deteta as pastas exportadas (Atividades, Métricas de atividade diária, Todas as sessões, Todos os dados) e devolve uma contagem das pastas e ficheiros válidos.
• Parâmetros: Nenhum argumento necessário.
• Exemplo de Chamada: scan_google_fit_data()

get_daily_activity

• Descrição: Extrai registos diários de contagem de passos (step_count), calorias despendidas (calories.expended), minutos ativos (active_minutes) e distância percorrida, ignorando ficheiros vazios.
• Parâmetros: Nenhum argumento necessário.
• Exemplo de Chamada: get_daily_activity()

get_workout_logs

• Descrição: Extrai sessões de treino, exercícios e segmentos de atividade física a partir das pastas Atividades e Todas as sessões.
• Parâmetros: Nenhum argumento necessário.
• Exemplo de Chamada: get_workout_logs()

get_sleep_records

• Descrição: Extrai registos e horários de sono dos ficheiros derived_com.google.internal.sleep.
• Parâmetros: Nenhum argumento necessário.
• Exemplo de Chamada: get_sleep_records()

read_fitness_file

• Descrição: Lê e interpreta o conteúdo bruto ou parseado de qualquer ficheiro localizado na pasta ./data.
• Parâmetros:
  • file_path (string, obrigatório): Caminho relativo do ficheiro dentro da pasta ./data.
• Exemplos de Valores de Parâmetro:
  • file_path="Métricas de atividade diária/Daily activity metrics.csv"
  • file_path="Todos os dados/derived_com.google.step_count.delta_com.google.android.fit.json"
  • file_path="Atividades/Atividades.csv"
• Exemplo de Chamada: read_fitness_file(file_path="Métricas de atividade diária/Daily activity metrics.csv")

---

2. Recursos e Templates de Recursos (Resources & Resource Templates)

Os recursos fornecem aos assistentes de IA leitura direta de dados através de URIs padrão.

fitness://summary (URI Direta)

• Descrição: Devolve um resumo executivo em JSON com o estado da ligação, total de ficheiros e ficheiros válidos detetados.
• Exemplo de URI de Acesso: fitness://summary

docs://documents (URI Direta)

• Descrição: Devolve uma lista JSON com os caminhos de todos os ficheiros disponíveis na pasta ./data.
• Exemplo de URI de Acesso: docs://documents

docs://documents/{doc_id} (Template de Recurso)

• Descrição: Template de URI parametrizado para aceder ao conteúdo de qualquer ficheiro individual.
• Parâmetro do Template: {doc_id} (Caminho relativo do ficheiro).
• Exemplos de URIs Completas para Acesso:
  • docs://documents/Métricas de atividade diária/Daily activity metrics.csv
  • docs://documents/Todos os dados/derived_com.google.calories.expended.json
  • docs://documents/Todas as sessões/Sessões.csv

---

3. Prompts

Os prompts são rotinas de análise pré-definidas que orientam a IA para tarefas específicas de coaching e análise.

analyze_progress

• Descrição: Orienta a IA a analisar a evolução de passos, distância, minutos ativos e calorias.
• Parâmetros:
  • period (string, opcional, padrão: "all"): Período temporal de análise.
• Exemplos de Valores de Parâmetro: "7_dias", "30_dias", "tudo"
• Exemplos de Utilização no Cliente de IA:
  • /analyze_progress period="7_dias"
  • /analyze_progress period="30_dias"

generate_workout_plan

• Descrição: Orienta a IA a criar um plano semanal de treinos e descanso adaptado ao histórico de atividades do utilizador.
• Parâmetros:
  • fitness_goal (string, opcional, padrão: "fitness_geral"): Objetivo de treino pretendido.
• Exemplos de Valores de Parâmetro: "hipertrofia", "perda_peso", "resistencia"
• Exemplos de Utilização no Cliente de IA:
  • /generate_workout_plan fitness_goal="hipertrofia"
  • /generate_workout_plan fitness_goal="perda_peso"

give_coaching_feedback

• Descrição: Orienta a IA a fornecer comentários e recomendações práticas diárias sobre o nível de atividade física e qualidade de sono.
• Parâmetros:
  • date (string, opcional, padrão: "mais_recente"): Data alvo para avaliação.
• Exemplos de Valores de Parâmetro: "hoje", "mais_recente", "2026-08-05"
• Exemplos de Utilização no Cliente de IA:
  • /give_coaching_feedback date="hoje"
  • /give_coaching_feedback date="2026-08-05"