> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chrisdoc.dev/hevy-mcp/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure Hevy MCP environment variables and options

> Reference for all Hevy MCP configuration options including HEVY_API_KEY, timeout, debug mode, CORS origins, and Sentry telemetry settings.

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.

<Warning>
  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.
</Warning>

## Environment variables

<ParamField body="HEVY_API_KEY" type="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
</ParamField>

<ParamField body="HEVY_MCP_API_TIMEOUT" type="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
</ParamField>

<ParamField body="HEVY_MCP_DEBUG" type="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
</ParamField>

<ParamField body="MCP_ALLOWED_ORIGINS" type="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
</ParamField>

<ParamField body="XDG_CACHE_HOME" type="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
</ParamField>

<ParamField body="SENTRY_DSN" type="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
</ParamField>

<ParamField body="SENTRY_RELEASE" type="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
</ParamField>

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

| Flag              | Description                                   |
| ----------------- | --------------------------------------------- |
| `-h`, `--help`    | Print supported options and exit.             |
| `-v`, `--version` | Print the installed package version and exit. |

You can verify your installed version at any time:

```bash theme={null}
npx -y hevy-mcp --version
```

<Note>
  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.
</Note>

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