Skip to main content
Most Hevy MCP issues fall into three categories — client configuration, authentication, and environment. Work through the relevant accordion below to identify and fix the problem. If none of these resolve your issue, see Getting help at the bottom of this page.

​
Common problems

After adding or changing a Hevy MCP entry in your client’s configuration file, the client must be restarted or reconnected before the change takes effect.Steps:
  1. Save your client configuration file.
  2. Fully quit and reopen the client application, or use the client’s “reconnect” / “reload MCP servers” option if one is available.
  3. Verify the server is listed in the client’s MCP server panel or tool list.
For Codex specifically, run the following command after restarting to confirm the entry is registered:
The output should include an entry named hevy. If it does not appear, check that you ran the codex mcp add command correctly and that the configuration was saved.
The npx runner requires Node.js 20 or newer. If the command fails immediately or prints a version error, update Node.js first.To verify that hevy-mcp can be downloaded and run:
Run this in a plain terminal (not inside the MCP client). If this command succeeds, the package is healthy and the issue is likely in the client configuration or the HEVY_API_KEY environment variable.If npx is not available at all, confirm that Node.js is installed and that the npm/npx binaries are on your PATH.
Codex stores its MCP configuration separately from Claude Desktop and Cursor. Use the Codex CLI to inspect the current state:
If a hevy entry does not appear, add it:
After the entry appears in codex mcp list, start a new Codex session. Existing sessions do not pick up MCP configuration changes automatically.
If the hosted endpoint returns a 401 or authentication error, check the following:
  1. The API key is active. Open the Hevy app, go to Settings → Developer, and confirm the key is listed and has not been revoked.
  2. The account has Hevy PRO. The Hevy API requires an active PRO subscription. A key from a non-PRO account will be rejected.
  3. The key is sent in the correct header. The hosted Worker expects the key as a bearer token:
    Do not include the word “Bearer” inside the key value itself, and do not send the key as a query parameter or in any other header.
  4. No extra whitespace. Copy the key directly from the Hevy app and avoid trailing spaces or newlines.
For local stdio setups (Claude Desktop, Cursor, Docker, or any stdio client), the API key must be available to the MCP child process via the HEVY_API_KEY environment variable.Common causes of local authentication failures:
  • The env block in your MCP client config is missing or the key name is misspelled (HEVY_API_KEY is case-sensitive).
  • The key was set in your shell session but not in the client config — the child process does not inherit your interactive shell environment automatically in most clients.
  • The key has been rotated in the Hevy app but the config still contains the old value.
Verify the key is reachable by running:
If that succeeds, the key itself is valid. Update the env block in your client config with the same value and restart the client.
Set the HEVY_MCP_DEBUG environment variable to exactly 1 to enable diagnostic output:
Or in your MCP client config env block:
Diagnostic output is written to stderr. It does not interfere with MCP JSON-RPC messages, which are written to stdout. Most MCP clients display stderr output in a separate log panel or surface it in the developer console.
If tool calls fail with timeout errors, the default 30-second limit may be too short for large paginated responses (for example, fetching a very large exercise template catalog).Adjust the timeout using the HEVY_MCP_API_TIMEOUT environment variable (value in milliseconds):
If the value supplied is not a positive integer, the server falls back to the default of 30,000 ms (30 seconds).

​
Getting help

If you have worked through the steps above and the issue persists, open an issue on GitHub: https://github.com/chrisdoc/hevy-mcp/issues Include the following in your report:
  • Your MCP client name and version
  • How you are running Hevy MCP (hosted endpoint, npx, Docker, etc.)
  • The error message or unexpected behavior you observed
  • The output of HEVY_MCP_DEBUG=1 if applicable
HEVY_MCP_DEBUG=1 enables privacy-bounded diagnostics — it does not log the API key value but does emit request and response metadata (tool names, argument shapes, HTTP status codes, and timing) to stderr. This output is safe to include in a GitHub issue.

Configuration

Full reference for HEVY_API_KEY, timeout, debug, and CORS settings.

Security

Best practices for API key handling and mutation safety.