Apple Health Data with Elasticsearch

Servidor MCP para datos de Apple Health con Elasticsearch - Proyecto inicial

¡Bienvenido! Este repositorio contiene el código fuente completo y final para la publicación del blog, "Desbloquea el potencial de tu LLM: Construyendo un servidor MCP con Elasticsearch para datos de salud reales".

Este proyecto proporciona una implementación ejecutable de un servidor personalizado del Protocolo de Contexto de Modelo (MCP). Construido con Python y el framework FastMCP, este servidor se conecta a un índice de Elasticsearch que contiene datos de pasos de muestra de Apple HealthKit. Esta configuración permite que un cliente LLM como Claude consulte datos de salud personales usando lenguaje natural.

Requisitos previos

Antes de comenzar, asegúrate de tener instalado y en ejecución lo siguiente:

• Python 3.10+
• Elasticsearch: Una instancia de Elasticsearch 8.x ejecutándose localmente en http://localhost:9200.
• Claude Desktop: El cliente MCP que usaremos para interactuar con el servidor.
• uv: Para gestionar paquetes de Python.

Comenzando

Sigue estos pasos para configurar tu entorno local e instalar las dependencias necesarias.

1. Navega a tu directorio de proyecto

Abre tu terminal o símbolo del sistema y navega a la carpeta del proyecto.

cd path/to/your/folder/apple-watch-health-mcp

2. Inicializa el proyecto de Python

Este paso crea el archivo pyproject.toml, que uv usa para gestionar las dependencias de tu proyecto.

uv init

3. Crea y activa un entorno virtual

# Create the virtual environment
uv venv

# Activate the environment
# On macOS/Linux:
source .venv/bin/activate

# On Windows:
.venv\Scripts\activate

4. Instala las dependencias

Instala los paquetes de Python necesarios. Ten en cuenta que estamos especificando una versión compatible para la biblioteca elasticsearch para que coincida con el servidor v8.x utilizado en este tutorial.

uv add "mcp[cli]" "elasticsearch>=8.0.0,<9.0.0" aiohttp pydantic

Configuración del entorno

Configuración de la clave API

Después de crear la clave API en Elasticsearch, debes configurarla en tu entorno:

# Export the API key for the current session
export ES_API_KEY="your_encoded_api_key_here"

Instrucciones de uso

Con el entorno configurado, ahora puedes ejecutar la solución.

1. Ingesta los datos de muestra

Primero, ejecuta el script proporcionado para poblar tu instancia de Elasticsearch con los datos de muestra. Este script creará el índice con el mapeo correcto e insertará los 30 documentos de muestra.

python ingest_data.py

Deberías ver una salida que confirme que los documentos se ingirieron correctamente.

2. Prueba el servidor con MCP Inspector

Antes de instalar en Claude, puedes verificar que el servidor funciona correctamente usando la herramienta MCP Inspector.

mcp dev apple_watch_mcp.py

Esto abrirá una interfaz web donde podrás probar interactivamente los recursos, herramientas y prompts del servidor.

3. Instala y usa en Claude

Este es el paso final para conectar tu servidor MCP al cliente Claude Desktop.

1. Instala el servidor: Ejecuta este comando en tu terminal.

   mcp install apple_watch_mcp.py --name "Apple Health Steps"
   

   Este comando registra el servidor en el archivo de configuración de Claude Desktop.

   Ejecuta el comando a continuación para ver el contenido de este archivo.

   
       cat ~/Library/Application\ Support/Claude/claude_desktop_config.json  
   
   

Deberías ver una estructura similar a esta dentro del archivo, bajo la clave "mcpServers":

{
 "mcpServers": {
   "Apple Health Steps": {
     "command": "/full/path/to/your/uv",
     "args": [
       "--directory",
       "/path/to/repository/apple-watch-health-mcp",
       "run",
       "apple_watch_mcp.py"
       // Other arguments may appear depending on your setup
     ]
   }
   // ... other servers might be listed here
 }
}

2. Reinicia Claude Desktop: Debes cerrar y volver a abrir la aplicación Claude Desktop para que cargue la nueva configuración del servidor.

3. Comienza a chatear: Una vez reiniciado, Claude ejecutará automáticamente tu servidor MCP en segundo plano. Ahora puedes hacerle preguntas sobre tus datos de salud en lenguaje natural. Prueba estos ejemplos de la publicación del blog:

   • "¿Cuál fue mi día más activo esta semana?"
   • "Compara mi actividad entre Apple Watch y iPhone"
   • O usa los comandos de barra incorporados como /daily_report o /trend_analysis.

Descripciones de archivos

• apple_watch_mcp.py: El script completo y final para el servidor MCP, que contiene todos los Recursos, Herramientas y Prompts implementados.
• ingest_data.py: Un script auxiliar que puebla tu instancia de Elasticsearch con los datos de muestra.
• sample_data.json: Un archivo JSON que contiene datos ficticios de conteo de pasos de Apple Health para pruebas.
• README.md: Este archivo, que proporciona instrucciones para ejecutar la solución completa.