Amazfit MCP

A Model Context Protocol server that gives any MCP-capable AI agent read access to your Zepp / Amazfit data: workouts with decoded GPS/HR/pace/power tracks, per-km splits and HR zones, daily activity and sleep stages, readiness/HRV, PAI, stress, blood oxygen, and devices. It can also create structured workouts and schedule them on the Zepp training calendar, which syncs them to the watch.

It logs in to the Zepp cloud through Zepp's web-app login flow (the same one user.zepp.com uses), so it does not sign your phone's Zepp app out. No phone, root, or Bluetooth required.

Tools

Dates are ISO YYYY-MM-DD in local time. Workout sport names come from Zepp's numeric type codes; unmapped codes show as unknown (type N). Add them to SPORT_NAMES in normalize.py.

Related MCP server: zepp-mcp

Requirements

• Python 3.12+

• uv

• A Zepp / Amazfit account (email + password login)

Setup

git clone https://github.com/fjuliofontes/amazfit-mcp.git
cd amazfit-mcp
uv sync                            # install dependencies
cp .env.example .env               # then add your Zepp credentials to .env
uv run python test_connection.py   # exercise every tool live
uv run pytest                      # offline unit tests

Configuration

Settings are read from environment variables, loaded from the .env next to server.py:

ZEPP_EMAIL=you@example.com
ZEPP_PASSWORD=your-zepp-password
# optional
ZEPP_COUNTRY=US                    # login country code; change if login fails
ZEPP_TIMEZONE=Europe/Lisbon        # IANA name; default: machine local time
ZEPP_DEVICE_NAMES=10289411=My Band # name devices missing from the built-in table
ZEPP_TOKEN_CACHE=~/.cache/amazfit-mcp/auth.json   # or "off"

.env is listed in .gitignore and is never committed.

Connecting an AI agent

Add the server to your agent's MCP configuration — for example Claude Desktop (claude_desktop_config.json), Claude Code (.mcp.json), or Cursor. Replace /path/to/amazfit-mcp with the absolute path to your clone:

{
  "mcpServers": {
    "amazfit": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/amazfit-mcp",
        "python",
        "server.py"
      ]
    }
  }
}

uv run --directory sets the working directory so the server loads credentials from that folder's .env. If you prefer to pass credentials inline instead, add an "env" block (not recommended for shared or committed config files):

"env": {
  "ZEPP_EMAIL": "you@example.com",
  "ZEPP_PASSWORD": "your-zepp-password"
}

Security

• Credentials live only in your local .env, which is git-ignored. Never commit real credentials, and avoid inlining them in MCP config files that may be shared or version-controlled.

• The login token is cached at ~/.cache/amazfit-mcp/auth.json with 0600 permissions so restarts don't log in again. An expired token is replaced automatically. Set ZEPP_TOKEN_CACHE=off to keep it in memory only.

• Device Bluetooth auth keys returned by the API are never exposed to the agent.

• All traffic is over HTTPS. Error messages never include credentials.

Notes

• Login uses the web-app identity (com.huami.webapp). The previous huami-token-based login registered as an Android phone and signed the phone app out.

• The track decoder (decoder.py) and device table (known_devices.py) are shared with dreeve-zepp-connector, where each field's encoding was reverse-engineered and verified against Zepp's own FIT exports.

• Workout history is paged 500 at a time (via count; Zepp ignores limit) and cached for 5 minutes.

• HTTP 429s and connection errors are retried with exponential backoff.

Credits

• Originally forked from drfittri/zepp-mcp by Mohd Fittri Fahmi. Thanks for the starting point.

• Web-app login flow from effectpears/zepp-downloader.

• Track decoding based on rolandsz/Mi-Fit-and-Zepp-workout-exporter and mireq/MiFitDataExport, extended in dreeve-zepp-connector.

• Data-call headers adapted from huami-token.

License

MIT

Disclaimer

This is an unofficial client that uses a reverse-engineered Zepp cloud API. It is not affiliated with or endorsed by Zepp Health / Huami. Use it with your own account and at your own risk.