voltras-mcp

An MCP (Model Context Protocol) server that turns a Voltra digital-resistance trainer into something Claude can drive: connect to the device, set the load, record sets and reps, run analytics over the history, and coach you through a workout out loud. It also ships a local web dashboard so you can watch the set happen on a screen instead of in a chat log.

Stdio transport only — one server process per Claude Code session.

• Requirements — Node 22.5+, and (for real hardware) Bluetooth setup
• Quickstart — clone, build, register with Claude Code
• Your first workout — including a no-hardware path you can run right now
• The dashboard — two front ends, one sidecar
• Environment variables
• Running more than one instance — the most common way to break it
• Tool catalog and Push events
• Troubleshooting

---

Requirements

Node >= 22.5.0. The store is built on node:sqlite, which does not exist in older releases. This is newer than the default on most machines — check before you start:

node --version    # must be v22.5.0 or later

There is no automatic preflight check for this; on an older Node the server fails at startup with a module-resolution error for node:sqlite, which is not an obvious message.

For real hardware (macOS):

• Bluetooth permission. The BLE adapter runs inside whatever process launched the server — normally your terminal app, or the Claude Code desktop app. macOS grants Bluetooth access per-app, so the first scan triggers a permission prompt attached to that app. If you dismissed it, re-grant under System Settings → Privacy & Security → Bluetooth. Without it, device.scan returns no devices and gives no other clue.
• Xcode Command Line Tools (xcode-select --install). The real BLE path pulls @stoprocent/noble (an optional dependency of @voltras/node-sdk), which is a native module. It ships prebuilt macOS binaries, but those are tied to specific Node ABI versions — on a recent Node it falls back to compiling from source with node-gyp, which needs the Command Line Tools. Because it is an optional dependency, a failed build does not fail npm install; you only find out later when connecting doesn't work.

No hardware? Set VOLTRA_ADAPTER=mock and skip both of the above. See without a device.

Claude Code for the MCP client, and for the optional push-event stream, v2.1.80 or later (see push events).

---

Quickstart

The package is not published to npm. Older instructions that say npx voltras-mcp do not work — clone and build it.

git clone <this-repo> voltras-mcp
cd voltras-mcp

npm install              # ~1000 packages
npm run build            # tsc → dist/ (this produces the server binary)
npm run build:dashboard  # vite → dist/spa (this produces the web dashboard)

Both build steps matter. npm run build alone gives you a working MCP server whose dashboard /app route serves only a "SPA not built" placeholder.

Register it with Claude Code, pointing at the built entry point:

claude mcp add voltras -- node "$PWD/dist/bin.js"

Then restart Claude Code. The voltras server's tools and resources should appear; ask Claude to call server.health to confirm the connection end to end.

<details> <summary>Alternative: register via <code>npm link</code></summary>

npm link                              # exposes the `voltras-mcp` bin globally
claude mcp add voltras -- voltras-mcp

Equivalent, but the absolute-path form above has fewer moving parts and survives npm link being cleared by an unrelated global install.

</details>

To pass configuration, use -e:

claude mcp add voltras