Withings

Servidor MCP para integração de dados de saúde da Withings

GitHub
44

Documentação

Servidor MCP Withings

Ajude-me a pagar pelos servidores no Patreon

Quality Gate Status Bugs Code Smells Lines of Code Reliability Rating Security Rating Maintainability Rating Vulnerabilities

Um servidor Model Context Protocol (MCP) que traz seus dados de saúde da Withings para o Claude. Acesse seus padrões de sono, medidas corporais, treinos, dados cardíacos e muito mais por meio de conversa natural.

🔒 Privacidade em Primeiro Lugar: Este é meu projeto pessoal, e o repositório é intencionalmente público para demonstrar transparência. O código mostra que nenhuma informação pessoal é registrada ou armazenada de forma maliciosa. Todos os dados sensíveis (tokens, IDs de usuário) são criptografados em repouso e automaticamente removidos dos logs. Você pode revisar todo o código-fonte para verificar esse compromisso com a privacidade.

⚠️ Aviso: Este servidor é fornecido como está, sem garantias ou garantias. Embora eu tenha feito todos os esforços para garantir segurança e privacidade, não ofereço garantias sobre disponibilidade, integridade de dados ou segurança. Use por sua conta e risco. Para casos de uso em produção, considere hospedar sua própria instância.

Configuração Rápida

  1. Abra o Claude Desktop → Personalizar → Conectores
  2. Clique em + → Adicionar Conector Personalizado
  3. Defina a URL como https://withings-mcp.com/mcp → clique em Adicionar
  4. Clique em Conectar e autorize com sua conta Withings

É isso! Pergunte ao Claude sobre seu sono, peso, treinos ou dados cardíacos.

Demonstração

Demo

Sumário

O Que Você Pode Fazer Com Isso?

Este servidor MCP dá ao Claude acesso aos seus dados de saúde da Withings, permitindo que você:

  • Analise seu sono: Pergunte sobre qualidade do sono, duração, estágios de sono profundo, frequência cardíaca durante o sono
  • Acompanhe métricas corporais: Tendências de peso, composição corporal, pressão arterial, frequência cardíaca ao longo do tempo
  • Revise treinos: Analise padrões de exercício, calorias queimadas, zonas de frequência cardíaca
  • Monitore a saúde cardíaca: Acesse gravações de ECG e dados cardíacos detalhados
  • Defina e acompanhe metas: Revise suas metas de condicionamento físico e saúde
  • Identifique padrões: Encontre correlações entre sono, atividade e outras métricas
  • Gere insights: Obtenha análises com IA sobre suas tendências de saúde

Tudo por meio de conversa natural com o Claude ou qualquer outro cliente compatível com MCP.

Para Usuários Finais: Usando o Servidor Hospedado

Se você só quer usar este servidor MCP com o Claude Desktop sem hospedar nada, siga estes passos:

Pré-requisitos

  1. Uma conta Withings com dispositivos conectados
  2. Claude Desktop ou qualquer outro cliente compatível com MCP instalado no seu computador

Instruções de Configuração

Passo 1: Adicionar Conector no Claude Desktop

  1. Abra o Claude Desktop
  2. Vá para Personalizar (na barra lateral ou menu)
  3. Navegue até a seção Conectores
  4. Clique no botão + para adicionar um novo conector
  5. Selecione Adicionar Conector Personalizado
  6. Preencha os seguintes detalhes:
    • Nome: Withings (ou qualquer nome que preferir)
    • URL do servidor MCP remoto: https://withings-mcp.com/mcp
  7. Clique em Adicionar

Nota: Se seu cliente MCP não suportar configuração de conector baseada em interface, você pode editar manualmente o arquivo de configuração. Veja o guia de configuração manual abaixo.

Passo 2: Conectar e Autorizar

  1. Nas configurações de Conectores, encontre o conector Withings que você acabou de adicionar
  2. Clique em Conectar ao lado do conector
  3. Seu navegador abrirá com a página de autorização da Withings
  4. Faça login na sua conta Withings
  5. Revise e aprove as permissões solicitadas
  6. Você será redirecionado de volta e a conexão estará completa

Após a autorização, o Claude terá acesso aos seus dados da Withings!

Ferramentas Disponíveis

Uma vez conectado, o Claude pode usar estas ferramentas para acessar seus dados:

Sono e Atividade

  • get_hrv - RMSSD, SDNN e pontuações de qualidade em nível de minuto capturados durante o sono
  • get_sleep_summary - Duração do sono, estágios (leve/profundo/REM), frequência cardíaca, respiração, pontuação do sono
  • get_activity - Passos diários, distância, calorias, elevação, durações de atividade
  • get_intraday_activity - Dados de atividade de alta frequência ao longo do dia
  • get_workouts - Resumos detalhados de treinos com zonas de frequência cardíaca e métricas

Medidas Corporais

  • get_measures - Peso, composição corporal, pressão arterial, frequência cardíaca, temperatura, VO2 máximo e mais

Dispositivos e Metas

  • get_user_devices - Lista de dispositivos Withings conectados
  • get_user_goals - Suas metas de saúde e condicionamento físico (passos, sono, peso)

Saúde Cardíaca

  • list_heart_records - Lista de gravações de ECG
  • get_heart_signal - Dados detalhados da forma de onda do ECG

Estetoscópio (se você tiver BPM Core)

  • list_stetho_records - Lista de gravações de estetoscópio
  • get_stetho_signal - Dados detalhados do sinal de áudio

Exemplos de Conversas

Tente perguntar ao Claude:

  • "Como tem sido a qualidade do meu sono na última semana?"
  • "Mostre-me minha tendência de peso no último mês"
  • "Qual é minha frequência cardíaca média em repouso?"
  • "Eu atingi minha meta de passos esta semana?"
  • "Compare a intensidade dos meus treinos entre este mês e o mês passado"
  • "Quando dormi melhor neste mês?"

Privacidade e Segurança

  • Tokens criptografados: Todos os tokens de autenticação e códigos de autorização são criptografados usando AES-256-GCM antes do armazenamento
  • Sem registro de dados pessoais: O código é público - você pode verificar que nenhuma informação sensível é registrada
  • Redação automática: Todos os IDs de usuário, tokens e credenciais são automaticamente removidos dos logs do sistema
  • OAuth 2.0: Autenticação segura padrão da indústria com suporte a PKCE e validação de URI de redirecionamento
  • Segurança de sessão: Sessões MCP são vinculadas ao usuário autenticado, prevenindo acesso entre usuários
  • Você no controle: Revogue o acesso a qualquer momento nas configurações da sua conta Withings

Para Desenvolvedores: Auto-Hospedagem

Quer executar sua própria instância? Veja como implantar este servidor MCP você mesmo.

Pré-requisitos

  1. Bun 1.1+ instalado
  2. Uma Conta de Desenvolvedor Withings

Passo 1: Criar Aplicação Withings

  1. Vá para o Portal do Desenvolvedor Withings
  2. Crie uma nova aplicação
  3. Anote seu Client ID e Client Secret
  4. Defina sua URI de Redirecionamento para: https://your-domain.com/callback
    • Deve ser uma URL publicamente acessível (localhost não é suportado pela Withings)
    • Pode ser qualquer domínio onde você hospedará o servidor (ex.: Fly.io, Railway, seu próprio servidor, etc.)

Importante: Remover Google Analytics

A versão hospedada inclui uma tag do Google Analytics (G-ZMGF9WXL3W) nas páginas estáticas em public/. Se você estiver fazendo um fork deste repositório, remova ou substitua o trecho do GA em public/index.html e public/health.html, e atualize os cabeçalhos CSP em src/server/app.ts de acordo.

Passo 2: Clonar e Configurar

# Clone the repository
git clone https://github.com/your-username/withings-mcp.git
cd withings-mcp

# Install dependencies
bun install

# Generate encryption secret
bun run generate-secret
# Copy the output - you'll need it for environment variables

Passo 2.5: Configurar Banco de Dados Supabase

  1. Crie um projeto gratuito no Supabase
  2. Instale a CLI do Supabase: bun install -g supabase (ou use brew install supabase/tap/supabase)
  3. Vincule seu projeto: supabase link --project-ref <your-project-ref>
  4. Aplique as migrações do banco de dados: supabase db push
  5. Obtenha suas credenciais em Dashboard → Configurações → API:
    • URL do Projeto → SUPABASE_URL
    • Chave de função de serviço → SUPABASE_SECRET_KEY

Passo 3: Desenvolvimento Local

Nota: A Withings exige uma URL publicamente acessível para callbacks OAuth. Para desenvolvimento local, use um serviço de tunelamento para expor seu servidor local ou implante em um ambiente de staging para testes.

# Copy environment template
cp .env.example .env

# Edit .env with your values
# WITHINGS_CLIENT_ID=your_client_id
# WITHINGS_CLIENT_SECRET=your_client_secret
# WITHINGS_REDIRECT_URI=https://your-tunnel-url.com/callback
# ENCRYPTION_SECRET=paste_generated_secret_here
# SUPABASE_URL=https://your-project.supabase.co
# SUPABASE_SECRET_KEY=your_service_role_key
# PORT=3000

# Run locally (Bun executes TypeScript directly — no build step)
bun run dev

Certifique-se de que sua URI de redirecionamento no arquivo .env corresponda à URL publicamente acessível que aponta para seu servidor local.

Passo 4: Implantar em Produção

# The project runs TypeScript directly with Bun — no build step required.
bun run start

Implante na Plataforma de Aplicativos DigitalOcean (seu buildpack Bun detecta package.json e executa bun run start automaticamente), ou em qualquer outro host que suporte Bun.

Defina as seguintes variáveis de ambiente em sua plataforma de hospedagem:

VariávelObrigatóriaExemplo
WITHINGS_CLIENT_IDSimyour_client_id
WITHINGS_CLIENT_SECRETSimyour_client_secret
WITHINGS_REDIRECT_URISimhttps://your-domain.com/callback
ENCRYPTION_SECRETSimGerada no passo 2
SUPABASE_URLSimhttps://your-project.supabase.co
SUPABASE_SECRET_KEYSimSua chave de função de serviço do Supabase
PORTNão3000 (ou o padrão da sua plataforma)
LOG_LEVELNãoinfo
ALLOWED_ORIGINSNãohttps://example.com,https://app.example.com

Passo 5: Atualizar Configurações do Aplicativo Withings

Volte ao seu aplicativo de desenvolvedor Withings e atualize a URI de redirecionamento para corresponder à sua URL implantada: https://your-domain.com/callback

Passo 6: Configurar Seu Cliente MCP

Para Claude Desktop:

  1. Abra o Claude Desktop
  2. Vá para Personalizar → seção Conectores
  3. Clique no botão + e selecione Adicionar Conector Personalizado
  4. Preencha os seguintes detalhes:
    • Nome: Withings (ou qualquer nome que preferir)
    • URL do servidor MCP remoto: https://your-domain.com/mcp
  5. Clique em Adicionar
  6. Clique em Conectar ao lado do conector para autorizar

Para Outros Clientes MCP:

Configure seu cliente MCP com os seguintes detalhes de conexão:

  • URL do servidor: https://your-domain.com
  • Transporte: HTTP Streamable
  • Endpoint: /mcp
  • Autenticação: OAuth 2.0
  • URL de descoberta: /.well-known/oauth-authorization-server

Referência de Variáveis de Ambiente

VariávelObrigatóriaDescrição
WITHINGS_CLIENT_IDSimSeu client ID do aplicativo Withings
WITHINGS_CLIENT_SECRETSimSeu client secret do aplicativo Withings
WITHINGS_REDIRECT_URISimURL de callback OAuth (deve corresponder às configurações do aplicativo Withings)
ENCRYPTION_SECRETSimSegredo de 32+ caracteres para criptografia de tokens (gere com bun run generate-secret)
SUPABASE_URLSimURL do seu projeto Supabase (de Dashboard → Configurações → API)
SUPABASE_SECRET_KEYSimSua chave de função de serviço do Supabase (de Dashboard → Configurações → API)
PORTNãoPorta do servidor (padrão: 3000)
LOG_LEVELNãoNível de registro: trace, debug, info, warn, error (padrão: info)
ALLOWED_ORIGINSNãoLista separada por vírgulas de origens CORS permitidas para clientes de navegador

Comandos de Desenvolvimento

bun run start            # Run the server
bun run dev              # Hot-reload mode
bun run typecheck        # Type-check with tsc (no emit)
bun run build            # Bundle for production (outputs to ./build)
bun run generate-secret  # Generate encryption secret for ENCRYPTION_SECRET env variable

Estrutura do Projeto

src/
├── auth/              # OAuth 2.0 authentication & token storage
├── db/                # Supabase client & cleanup scheduler
├── server/            # Hono app, MCP endpoints, middleware
├── tools/             # MCP tools for Withings API (sleep, measure, user, heart, stetho)
├── types/             # TypeScript type definitions (Hono, Withings API)
├── withings/          # Withings API client
├── utils/             # Logger and encryption utilities
└── index.ts           # Main entry point

supabase/
└── migrations/        # Database schema migrations

Veja CLAUDE.md para documentação detalhada da arquitetura.

Recursos de Segurança

Criptografia de Tokens

Todos os tokens de acesso, tokens de atualização e códigos de autorização da Withings são criptografados em repouso usando AES-256-GCM:

  • Algoritmo: AES-256-GCM (criptografia autenticada)
  • Derivação de chave: PBKDF2 com 100.000 iterações
  • Defesa em profundidade: Mesmo que o banco de dados seja comprometido, os tokens permanecem protegidos Importante: Mantenha seu ENCRYPTION_SECRET:
  • Pelo menos 32 caracteres
  • Gerado aleatoriamente (use bun run generate-secret)
  • Seguro e nunca commitado no controle de versão
  • Consistente entre reinicializações do servidor

Endurecimento OAuth

  • Validação de URI de redirecionamento: O endpoint /authorize valida redirect_uri contra as URIs permitidas do cliente registrado, prevenindo ataques de redirecionamento aberto
  • Códigos de autorização de uso único: Códigos de autorização são consumidos atomicamente para prevenir ataques de replay (conforme RFC 6749)
  • Suporte a PKCE: Método de desafio de código SHA-256 para segurança aprimorada
  • Validação na inicialização: O servidor se recusa a iniciar se as variáveis de ambiente necessárias estiverem ausentes

Segurança de Transporte

  • Vínculo de token de sessão: Sessões MCP são vinculadas ao token de portador que as criou, prevenindo sequestro de sessão entre usuários
  • Validação JSON-RPC: Todas as mensagens recebidas são validadas contra a especificação JSON-RPC 2.0 antes do processamento
  • Limites de corpo de requisição: Limite global de 1MB para prevenir esgotamento de memória
  • Redirecionamento HTTPS: Requisições HTTP são automaticamente redirecionadas para HTTPS em produção
  • CSP estrito: Política de Segurança de Conteúdo sem diretivas unsafe-inline
  • Limitação de taxa atômica: Função PostgreSQL com bloqueio em nível de linha previne condições de corrida

Registro de Logs com Privacidade

O logger personalizado redige automaticamente todas as informações sensíveis:

  • ✅ Eventos operacionais e erros registrados
  • ❌ Sem tokens, credenciais ou códigos de autorização
  • ❌ Sem IDs de usuário ou informações pessoais
  • ❌ Sem payloads de requisição/resposta da API com dados sensíveis

Você pode revisar a implementação de logging em src/utils/logger.ts.

Contribuindo

Este é um projeto pessoal, mas contribuições são bem-vindas! Por favor:

  1. Faça um fork do repositório
  2. Crie um branch de funcionalidade
  3. Faça suas alterações
  4. Envie um pull request

Licença

Licença MIT - veja o arquivo LICENSE para detalhes.

Suporte

Agradecimentos

Construído com: