runalyze

Runalyze MCP Server exposes your Runalyze health metrics (such as HRV, Sleep, Resting Heart Rate, and Activities) to AI assistants via the MCP protocol. The local setup runs a Node.js server that you start on your machine, while the hosted setup provides a remote instance you can query directly. Once running, you can configure your preferred AI tool (Claude Desktop, ChatGPT Desktop, or code editors with MCP support) to communicate with the server by pointing it at the MCP entry point and supplying your Runalyze API token when required. The server acts as an intermediary, translating MCP requests from your AI tool into Runalyze API calls and returning structured results suitable for natural language prompts and conversational workflows. If you choose the hosted version, you can still supply your API token per request, and the hosted server will fetch data from Runalyze without you needing to self-host.

Prerequisites:

• Node.js v18+ installed on your machine
• Yarn package manager
• A Runalyze account with premium access
• An AI assistant that supports MCP (e.g., Claude Desktop, ChatGPT Desktop, VS Code MCP extensions)

Step 1: Clone the repository

# Clone the repository
git clone https://github.com/floriankimmel/runalyze-mcp-server.git
cd runalyze-mcp-server

Step 2: Install dependencies Option A (Devbox is recommended if you use it):

# Install devbox and direnv (macOS example)
brew install devbox direnv

Option B (Manual setup):

# Install dependencies
yarn install

Step 3: Build the server Option A (Devbox):

devbox run build

Option B (Manual):

yarn build

The compiled server will be in the dist/ directory.

Step 4: Obtain your Runalyze API token

1. Log in to your Runalyze account
2. Go to Settings → Personal API: https://runalyze.com/settings/personal-api
3. Generate a new token and copy it for later use

Step 5: Run or prepare to run the server locally

• If you run locally, start the server that was built in dist/ (e.g., node dist/main.js) and ensure the RUNALYZE_API_TOKEN environment variable is set:

RUNALYZE_API_TOKEN=your-api-token-here node dist/main.js

• If you prefer the hosted version, you can skip local build and use the hosted endpoint described in Option 2 of the README.

Tips:

• Ensure your RUNALYZE_API_TOKEN has the necessary permissions for the data you request.
• When configuring your MCP client (Claude Desktop, ChatGPT Desktop, or editors), specify the node-based command and point arguments to the built entry file (dist/main.js). Use an absolute path for reliability.
• If you switch from local to hosted, remember to update your MCP client configuration to the hosted endpoint rather than the local file path.
• For hosted use, the server will require you to pass your token with each request; the hosted server does not store tokens persistently.
• Common issues usually involve incorrect token, wrong path to dist/main.js, or firewall/network restrictions blocking access to Runalyze APIs.