Sport Health MCP

A local-first MCP server for Huawei Sport Health analysis. Once a user provides their HUAWEI_HEALTH_* personal data export, the Agent can read exercise performance, in-workout physiological metrics, and health context before and after an activity, and supplement it with historical weather and air quality as needed.

This project is for workout review and does not provide medical diagnosis or treatment advice.

Current Capabilities

• Reconize Huawei personal data export directories and their core JSON files.

• Tolerantly parse non-standard numeric JSON keys from Huawei data.

• Parse activity summaries, GPS tracks, heart rate, cadence, speed, altitude, and training load.

• Aggregate heart rate, resting heart rate, HRV, stress, blood oxygen, and sleep stages for the day before, during, and after an activity.

• Call the Open-Meteo historical weather and air quality API and cache responses locally.

• Provide paginated data tools and a report evidence pack through MCP.

Related MCP server: Apple Health MCP

Installation

Python 3.11 or newer is recommended. Create a virtual environment in the project directory:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"

Huawei export packages are never packaged or committed; .gitignore ignores all HUAWEI_HEALTH_* directories by default.

Local Check

When the project directory contains exactly one HUAWEI_HEALTH_* folder, it is recognized automatically:

sport-health-inspect inspect
sport-health-inspect list

You can also specify it explicitly:

sport-health-inspect --export-dir "D:\HealthData\HUAWEI_HEALTH_xxx" list

Starting the MCP Server

For local agents, stdio is recommended:

$env:SPORT_HEALTH_EXPORT_DIR="D:\HealthData\HUAWEI_HEALTH_xxx"
sport-health-mcp

A minimal MCP client configuration looks like the following; the exact field names depend on the client:

{
  "mcpServers": {
    "sport-health": {
      "command": "C:\\sport-health-mcp\\.venv\\Scripts\\sport-health-mcp.exe",
      "env": {
        "SPORT_HEALTH_EXPORT_DIR": "D:\\HealthData\\HUAWEI_HEALTH_xxx"
      }
    }
  }
}

Registering with an MCP Client

Add the command and env settings shown above to any client that supports MCP stdio, save, and restart the client. Different clients place configuration files in different locations and may use different outer field names, so always check the corresponding client documentation.

Using Different Agents

• Same computer: any Agent that supports MCP stdio can launch the same Server, but it must be registered once using that Agent's configuration format.

• Another user's computer: install this project, export your own HUAWEI_HEALTH_* data package, and replace the command and data directory in the configuration with your own absolute paths.

• Web or cloud agents: a local stdio process on a user's computer is unreachable from such clients. To support them, you would need to provide a separate, authenticated Streamable HTTP deployment and handle encrypted uploads, user isolation, data deletion, and privacy compliance.

The project never shares the author's Huawei data. The MCP Server is a general-purpose program; every user keeps their data on their own machine.

MCP Tools

• inspect_huawei_export: Check the integrity of the data export.

• list_activities: List activities.

• get_activity_summary: Get a single activity's summary.

• get_activity_track: Get GPS tracks with pagination.

• get_activity_samples: Get heart rate, cadence, speed, and altitude samples with pagination.

• get_health_context: Get the health context of the days around an activity.

• get_activity_environment: Fetch and cache historical environmental data.

• get_report_evidence_pack: Generate a deterministic evidence pack for report writing.

• get_report_contract: Get the fixed report sections, length, and writing constraints.

The recommended flow is to call list_activities first, then pick an activity_id, call get_report_evidence_pack, and generate the report strictly so chapters the returned report_contract. The fixed format keeps only the essential assessments, performance analysis, body response, and training recommendations, and avoids repeating all metrics the device app already displays. Only use the paginated detail tools when you need to inspect the underlying curves or tracks.

Testing

No testing framework needs to be installed to run the standard-library tests:

$env:PYTHONPATH="src"
python -m unittest discover -s tests -v

Tests use only synthetic activity records generated by code; they do not depend on or contain any personal export data.

Privacy Boundaries

• Raw health data is only read locally by default.

• Only the environment enhancer touches the network, and it sends only the route center point plus a date and hour range.

• MCP tools are read-only; they do not modify Huawei export files.

• Before sharing logs or issue reports, remove coordinates, timestamps, device identifiers, and health indicators.

• When publishing code, do not zip the whole working directory; use a version-control export or publish build artifacts instead, to avoid including ignored personal data directories.

Open Source License

This project is released under the MIT License. Please read SECURITY.md before reporting a security issue, and do not upload real health data, GPS tracks, environment caches, or logs containing local paths to public issues.

Third-Party Services and Trademarks

• Data is provided by Open-Meteo, licensed under CC BY 4.0. The source and license information must be retained whenever the data is shown.

• The free Open-Meteo API is intended for non-commercial use and is subject to call quotas. For commercial use, use the commercial API or self-host under the official license. See Open-Meteo Terms.

• This project is an independent community project; it is not affiliated with, authorized by, or otherwise endorsed by Huawei. All product names and trademarks belong to their respective owners.