Skip to main content
The local stdio server is configured entirely through environment variables passed into its child process. No config file is read from disk, and no CLI flags accept runtime values — the flags that exist (-h, --help, -v, --version) are informational only. The hosted Cloudflare Worker has its own set of server-side variables (such as MCP_ALLOWED_ORIGINS) that are set at deploy time and are not visible to clients.
Never pass HEVY_API_KEY in a URL, a log statement, a CLI argument, or a shell history entry. Supply it only through the child-process env block in your MCP client configuration, or via a protected environment file. Treat it with the same care as a password.

​
Environment variables

​
HEVY_API_KEY
string
required
Your Hevy API key, generated in Settings → Account inside the Hevy app. Required for the local stdio server to authenticate with the Hevy API. The server exits with a non-zero code and a clear error message if this value is absent or empty.Scope: Local stdio
​
HEVY_MCP_API_TIMEOUT
integer
Maximum time in milliseconds to wait for a response from the Hevy API before the request is aborted. Must be a positive integer. Invalid or non-numeric values are silently ignored and the default is used.Default: 30000 (30 seconds)
Scope: Local stdio
​
HEVY_MCP_DEBUG
string
Set to exactly 1 to enable privacy-bounded diagnostic output. Diagnostics are written to stderr only; stdout remains reserved for MCP JSON-RPC messages and is never contaminated. Any value other than "1" (including "true", "yes", or "0") leaves debug mode disabled.Default: Disabled
Scope: Local stdio
​
MCP_ALLOWED_ORIGINS
string
Comma-separated list of exact origins that the self-hosted Cloudflare Worker will accept for browser-originated requests. Wildcards are intentionally unsupported. Requests that do not include an Origin header (such as desktop MCP clients) are always accepted regardless of this setting.Default: No browser origins allowed
Scope: Self-hosted Worker only
​
XDG_CACHE_HOME
string
Overrides the root directory used for the npm update-check cache file, which is written to <XDG_CACHE_HOME>/hevy-mcp/update-check.json. Useful in environments where the default ~/.cache path is not writable.Default: ~/.cache
Scope: Local stdio
​
SENTRY_DSN
string
Overrides the Sentry destination DSN for local Node.js telemetry. Set to an empty string ("") to disable Sentry export entirely. The hosted Cloudflare Worker does not import Node telemetry and ignores this variable.Default: Packaged project DSN
Scope: Optional local Node telemetry
​
SENTRY_RELEASE
string
Overrides the release label attached to local Sentry events and traces. Defaults to hevy-mcp@<installed-version> when not set. Useful when running a forked or custom build and you want events attributed to a distinct release.Default: hevy-mcp@<installed-version>
Scope: Optional local Node telemetry

​
CLI flags

The hevy-mcp binary accepts two informational flags. Both cause the process to print output and exit immediately — they are not valid runtime configuration for an MCP server session. You can verify your installed version at any time:
The local executable is stdio-only. It does not support PORT, HEVY_MCP_TRANSPORT, or --transport, and it does not start a local HTTP or SSE server. If your client requires HTTP or SSE transport, use the hosted Cloudflare endpoint instead.

​
Cache behavior

The search-exercise-templates tool and the hevy://exercise-templates resource share a server-scoped in-memory exercise template catalog cache:
  • TTL: Cached entries live for five minutes.
  • Size limit: The cache holds at most one catalog at a time.
  • Concurrent requests: When multiple requests arrive simultaneously, they share a single in-flight fetch rather than each triggering a separate Hevy API call.
  • Manual invalidation: Pass refresh: true to search-exercise-templates to bypass the cache and fetch a fresh catalog immediately.
  • Paginated fetches: Calls to get-exercise-templates always fetch their requested page directly and do not interact with the cache.
  • Hosted isolation: Each hosted Worker request receives a fresh cache instance, which prevents exercise template data from leaking between different users’ requests.