openGym MCP Bridge

A community-maintained, self-hosted MCP bridge for openGym. This is not an official openGym project.

• Reads the openGym account through its supported web/API interface and a dedicated paired token.

• Offers MCP tools for status, plan/history reads, official exercise-name search, guarded plan changes, and guarded historical workout logging.

• Supports confirmed, preview-first writes when OPENGYM_ALLOW_WRITES=1.

• v0.3.2 adds custom exercises, precise history queries, saved-workout edits, notes, phases, unilateral sets and mandatory local pre-write backups.

• Ships as a Docker image through GitHub Actions and GitHub Container Registry (GHCR).

This project is experimental. Back up your openGym data and inspect every write preview before confirming it.

The current published release is v0.4.0. This development branch prepares v0.4.1; no 0.4.1 image is published by a PR. See CHANGELOG, tool inputs/outputs and examples, openGym compatibility and limits, backup, recovery, upgrade and rollback procedures, and the development security review.

v0.4.1 compatibility maintenance (unreleased)

Targets official openGym v1.4.2 (e9a303877d02e4237b183f96a9a6603990e8fafb) and retains v1.4.1 compatibility CI. The optional text importer now verifies three immutable source files (including the independent muscle map), keeps Chinese names and explicit zero weights, and refuses partial/invalid downloads before replacing a catalogue. No official implementation or dataset is bundled.

get_weekly_training_summary adds per-muscle effective_sets and source accounting, keeping existing primary/secondary credits, sets, volume and trends. Valid explicit historical weights remain authoritative; entries without weights use the current catalogue. No training history is rewritten. get_plan and saved targets expose optional subs, warmupRestSec, warmupRestOff and sideRestSec; unrelated new state fields, including barDefaults and dayPhotos, stay intact. See v0.4.1 semantics and actual test evidence. All 37 tool names and write guards remain in place.

Related MCP server: tonal-mcp-cloudflare-workers

v0.4.0

This release adds existing-plan editing, persistent account-private workout drafts linked to exact A/B/C routine IDs, confirmed single-session completion, progress/weekly muscle-volume analysis and private bodyweight/feedback records. It skips v0.3.3. See v0.4.0 tools, safety and storage and the isolated acceptance report. All 155 regression tests and 15 official v1.4.1 compatibility groups pass. Real browser/PWA and Android device acceptance remains unverified; bodyweight/feedback records are not synchronized to the official app. Publishing a release does not upgrade an existing NAS deployment.

Docker image

ghcr.io/nirvana-z777/opengym-mcp-bridge:0.4.0

The image is built from this repository by .github/workflows/publish-image.yml. Pushing to main publishes the main tag. Pushing a version tag such as v0.4.0 publishes 0.4.0 and latest. GitHub Actions runs the full regression suite, pinned official API/frontend compatibility acceptance and isolated image checks before publishing; version-tag runs also verify anonymous pulls of both release tags.

Images target linux/amd64. Pin 0.4.0 or its verified digest for a release deployment; main tracks development and latest tracks the most recent stable release. The Dockerfile contains runtime source, package metadata and the MIT license; test fixtures and local configuration are excluded from its build context.

Security first

Never commit or bake any of the following into the repository or image:

• secrets/, opengym-token.json, mcp-access-token, openai-runtime-key

• .env, personal tunnel IDs/configuration, personal IP addresses or private workout exports

• store/ or other user data

The repository ignores local secret/data paths. The Docker build context also excludes them. Keep the Bridge behind the Docker network and do not publish its MCP port directly to the Internet. The example Compose file does not map a host port.

Quick deployment reference

1. Copy .env.example to .env and set OPENGYM_BASE_URL to the openGym address reachable from the Bridge container.

2. Copy docker-compose.example.yaml to your local docker-compose.yaml.

3. Create secrets/ and store/ locally. Pair the Bridge with openGym using its supported pairing flow; never paste pairing codes or tokens into public issues.

4. If using OpenAI Secure MCP Tunnel, copy tunnel-client.example.yaml to the local tunnel-client.yaml, replace the tunnel ID, and place the restricted runtime key and Bridge token in the expected files under secrets/.

5. Keep OPENGYM_ALLOW_WRITES=0 until you are ready to use the write tools. When enabled, every write still requires a short-lived preview and explicit confirmation.

6. Deploy with Docker Compose. The Bridge uses the GHCR image, not build: ..

The example files are templates, not a ready-to-run configuration. Do not publish your locally customized .env, docker-compose.yaml, tunnel-client.yaml, or secrets/.

MCP tools

Read-only tools include get_status, get_summary, get_plan, get_recent_workouts, and search_exercises. Writes are preview-first: preview_plan_change / apply_plan_change and preview_workout_log / log_workout. The apply/log tools are hidden when OPENGYM_ALLOW_WRITES is not 1.

History tools include list_custom_exercises, preview_custom_exercise_change / apply_custom_exercise_change, list_workouts, get_workout, get_exercise_history, and preview_workout_edit / apply_workout_edit. The draft workflow adds preview_finish_workout_draft / commit_finished_workout_draft; see the v0.4.0 tool reference for all 37 tools. Every upstream writer requires exact human confirmation 我确认写入, a fresh version check and a successful local backup. The existing Compose store mount places backups at /store/backups/, retaining 20 by default, and persists private drafts/feedback under /store/local/. No automatic restore writer exists. Notes and descriptions are untrusted data.

Historical workout logging accepts real recorded dates and actual per-set data. For each set, provide exactly one of reps or seconds; do not invent unknown dates, weights, repetitions, or durations.

Unilateral reps instead require actual sides.L and sides.R measurements; timed sides use separate flat rows. Optional phase, effort and weight_basis preserve the native model without converting historical weights. Refresh the optional text catalogue with node src/catalogue.mjs for full metadata checks before custom creation/renaming or derived-record edits. Date/time migration, legacy identity migration and unsupported complex structures are explicitly refused; read the compatibility limits before use.

Local development

Requires Node.js 22 or newer. The bridge has no npm runtime dependencies.

npm ci --ignore-scripts
npm test
npm start

All test identities, pairing codes, dates, body weights and per-set values are deliberately synthetic. Regression tests use mocked clients or temporary local files. The official compatibility matrix starts unmodified pinned v1.4.1 and v1.4.2 servers with new disposable accounts, and tests actual MCP processes and official frontend sync modules over local HTTP. It verifies all 37 tools, renewal, conflicts, lost responses and new configuration preservation; it never reads production credentials or history. CI requires at least all 155 baseline tests. MCP initialization reports the development version from package.json.

Pull requests also audit Docker context exclusion with synthetic canaries, build linux/amd64 and smoke-test MCP initialization with networking disabled. They do not receive package-write permission or publish images. Production upgrades remain a separate owner-approved operation.

Release process

1. Update the version in package.json, regenerate package-lock.json with npm install --package-lock-only --ignore-scripts, and update the pinned image in this README and docker-compose.example.yaml.

2. Run npm test locally.

3. Commit on a release/development branch, pass the full PR regression/official compatibility/image CI, then merge the approved PR into main; this publishes a main image for testing.

4. Create a GitHub Release and a tag such as v0.4.0 at the verified merge commit to publish 0.4.0 and latest. CI verifies that the tag matches package.json; a failed test prevents publication. Confirm both tags resolve to the reported publication digest and initialize with the expected version before announcing completion.

5. After the first package publication, set the GHCR package visibility to Public in the package settings if GitHub created it as private by default.

The workflow authenticates with the automatically provided GITHUB_TOKEN. Its test job has contents: read; only the publishing job also receives packages: write. No PAT, runtime API key, pairing token or tunnel credential is required for image publication. Actions are pinned to reviewed commit SHAs; update those pins when adopting an upstream release.

After making the package public, verify a pull without stored registry credentials on a machine with Docker:

anonymous_config=$(mktemp -d)
docker --config "$anonymous_config" pull --platform linux/amd64 ghcr.io/nirvana-z777/opengym-mcp-bridge:0.4.0
docker --config "$anonymous_config" pull --platform linux/amd64 ghcr.io/nirvana-z777/opengym-mcp-bridge:latest
rmdir "$anonymous_config"

License

MIT. See LICENSE.