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.

• 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.

Docker image

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

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.3.1 publishes 0.3.1 and latest. GitHub Actions runs npm test before publishing.

Images target linux/amd64. Pin 0.3.1 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.

Related MCP server: garmin-mcp

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.

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.

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. Tests use mocked clients or temporary local files and never read personal secrets or contact a real openGym account. CI rejects a test run that executes zero tests. MCP initialization reports the version from package.json.

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 and push to main to publish a main image for testing.

4. Create and push a tag such as v0.3.2 to publish 0.3.2 and latest. CI verifies that the tag matches package.json; a failed test prevents publication.

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.3.1
docker --config "$anonymous_config" pull --platform linux/amd64 ghcr.io/nirvana-z777/opengym-mcp-bridge:latest
rmdir "$anonymous_config"

License

MIT. See LICENSE.