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

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"

Servidor MCP para Google Fit (Google Takeout)