Preface

In DeepSeek Harness (DSH), creating personal health or running-related agents often involves manually writing scripts to pull from the Garmin API and then stuffing the JSON into the conversation context. With numerous data fields and varied authentication methods, it’s difficult for agents to automatically switch between tasks like “checking sleep,” “comparing recent running paces,” or “downloading FIT raw files.”

dsh-plugin-garmin-connect (GitHub repository Likenttt/garmin-connect-plugin-for-dsh) registers Garmin Connect as a set of AI-callable tools: after installing and configuring credentials, agents can trigger queries via natural language without needing to write HTTP requests each time. The plugin also provides a standalone MCP entry point, allowing the same set of tools to be reused in clients like Cursor, Codex, and Claude Code, without forcing dependence on the DSH web interface.

What Is This

The npm package name is dsh-plugin-garmin-connect, current version 0.1.5, MIT license, requires Node.js ≥ 20. Maintained by Likenttt, categorized as “Internet Tools” in the SkillHub community directory, with approximately 10 stars on GitHub.

The plugin mounts to DSH via @deepseek-ai/cordis, using the garmin-connect library under the hood to access Garmin Connect. In one sentence: it exposes activities, sleep, steps, heart rate, weight, training libraries, and limited write operations (downloading FIT, creating workouts) from your Garmin account as structured tools for models to call.

SkillHub (skillhub.cn) is an independent community directory for DSH plugins, with no official affiliation to DeepSeek / High-Flyer; installation and documentation should refer to the repository README and npm publication page.

Core Features

The plugin registers a total of 10 tools. Eight of them read-only Garmin data; download_garmin_activity_fit writes local files on the MCP/dsh host; create_garmin_workout modifies the user’s Garmin training library.

Tool Name Purpose
get_garmin_activities Recent exercise records, supports compact / full details
get_garmin_sleep Sleep score, duration, and stage distribution
get_garmin_steps Step count; goals and walking distance only appear when provided upstream by Garmin
get_garmin_heart_rate Resting, maximum, and minimum heart rate
get_garmin_weight Weight, BMI, body fat percentage, skeletal muscle mass, and other body composition metrics
get_garmin_workouts Reusable templates in the training library (not calendar schedules)
get_garmin_profile Profile summary filtered through a field whitelist
get_running_skill_advice Explains course types and training philosophies, or provides personalized running advice after completing queries
download_garmin_activity_fit Downloads activity archives and extracts the unique FIT file to the configured parent directory
create_garmin_workout Previews structured workouts; only creates after explicit user confirmation

create_garmin_workout uses a two-call process: the first returns a preview and a one-time confirmationId (valid for 10 minutes); after the user confirms the unchanged preview, a second call with confirmed: true and the same ID is made.

get_running_skill_advice distinguishes between two modes:

  • mode: "explain": Only explains course types or training philosophies (Hanson, Daniels, Norwegian threshold, polarized training, etc.), without generating a personal schedule.
  • mode: "personalized": Requires completing six sets of inquiries (goal, current performance, training background, available time, health constraints, training preferences); if any item is missing, it only returns follow-up questions, without reading Garmin activities or guessing plans. If hasWarningSymptoms is true, the tool stops safely and recommends medical evaluation, returning no course material.

Installation and Enabling

The environment requires Node.js ≥ 20 and pnpm in the PATH. First, prepare dependencies, then install the plugin.

npm install -g pnpm

It is recommended to install from the npm registry and activate the web profile (the first run will automatically initialize the profile):

npx --legacy-peer-deps=false @deepseek-ai/dsh plugin --profile web add dsh-plugin-garmin-connect

--legacy-peer-deps=false allows npm to properly resolve peer dependencies; if your local npm is configured with legacy-peer-deps=true, DSH might report ERR_MODULE_NOT_FOUND due to missing @deepseek-ai/cordis-plugin-group.

You can check if the plugin has been written to the configuration without starting the service:

npx --legacy-peer-deps=false @deepseek-ai/dsh --profile web --dump-config | grep -A 2 garmin-connect

If the DSH CLI is not yet installed, you can run:

npx --legacy-peer-deps=false @deepseek-ai/dsh web

The default web interface is http://127.0.0.1:3080. In Settings → Plugins → Plugin List, plugin-garmin-connect showing as mounted and enabled indicates successful loading.

Configuring Credentials

The plugin does not persist account passwords. Create a .env file in the root directory of the workspace running dsh (registry installation does not automatically bring out a template; refer to the repository’s .env.example). Choose one of GARMIN_PASSWORD, GARMIN_SESSION_TOKEN, or GARMIN_SESSION_TOKEN_FILE; a valid session takes precedence over password login.

GARMIN_USERNAME=your-email@example.com
GARMIN_PASSWORD=your-password
GARMIN_REGION=global

GARMIN_REGION can be global (international, default) or cn (Garmin China). When using the FIT download tool, you must additionally set GARMIN_FIT_DOWNLOAD_DIR to an absolute path parent directory.

Important Limitation in 0.1.5: Garmin two-step verification is not yet completed and is not supported in this release. The browser authentication commands in the README (garmin-connect-auth login --browser or source code npm run auth:setup) are only for local development debugging and should not be relied upon for production access or session recovery. On the MCP side, it can only read existing valid session files and will not prompt for MFA.

Typical Usage

After configuration, you can ask questions directly in natural language in the DSH web conversation, and the agent will select the appropriate tool:

  • “How did I sleep last night?”
  • “Help me check the pace changes in my last 5 runs.”
  • “How many steps did I take today?”

Examples of tool-layer parameters (for understanding the call format, typically automatically constructed by the agent):

{"limit": 5, "detail": "compact"}

{"startDate": "2023-10-01", "endDate": "2023-10-02"}

When explaining training philosophies, you can specify Chinese:

{"mode": "explain", "query": "Daniels", "language": "zh-CN"}

Without installing DSH, the npm package also provides a standalone MCP server (lib/mcp.js, system command garmin-connect-mcp). With a configured session, the same set of tools can be integrated into clients like Cursor, Codex, and Claude Code; see the repository README’s “Using in Other AI Programming Assistants (MCP Protocol)” section for configuration details.

Applicable Scenarios and Notes

Who is it for: Developers and individual users who have recorded exercise and health data in Garmin Connect and wish to use natural language queries or limited writes (creating workouts, exporting FIT) in DSH or other MCP clients.

Runtime Permissions: The plugin runs with the current dsh or MCP process permissions, can access credentials in the process environment variables, and writes FIT files or calls Garmin write APIs on the host machine. Before installation, review the source code and MIT license to ensure credential storage and file output paths comply with your local security policies.

Multi-Account and Session: The current model is “one account per process”—different clients or accounts should use independently initialized GARMIN_SESSION_TOKEN_FILEs and not concurrently share the same session file (refresh tokens may rotate). Multiple processes can share the same GARMIN_FIT_DOWNLOAD_DIR parent directory; the plugin will create subdirectories isolated by region and normalized email.

Data and Privacy: When GARMIN_ACTIVITY_DETAIL=full, activity data may include precise routes and locations; session tokens are as sensitive as passwords—do not paste them into AI conversations. download_garmin_activity_fit only returns activityId, fileName, sizeBytes, and sha256 to the model, not the full disk path.

Version and Ecosystem: Depends on @deepseek-ai/cordis ^4.0.1; DSH’s ecosystem philosophy is “everything is a plugin,” and this plugin is a community-maintained internet extension, not an official Garmin or DeepSeek product.

Links

By registering Garmin data as standard tools, health and running-related agents can skip a layer of API glue code and focus on conversation logic and training advice; at the 0.1.5 stage, the authentication process still primarily relies on passwords or existing sessions, and the browser MFA flow remains in development preview—please refer to the WARNING notes in the README before deployment.