Tonal MCP Server

A Model Context Protocol (MCP) server that provides LLMs with access to Tonal fitness data. Built on top of @dlwiest/ts-tonal-client, this server enables AI assistants to answer questions about your workouts, fitness progress, and muscle readiness.

Features

• 🏋️ Workout History - Access recent workout data and performance metrics
• 💪 Muscle Readiness - Get recovery status for workout planning
• 📊 Fitness Statistics - View lifetime stats, streaks, and progress trends
• 🎯 Movement Database - Browse and filter available Tonal exercises
• ✨ Workout Creation and Editing - Build and update custom workouts with per-set programming and supersets
• 🔧 Extensible Architecture - Easy to add new tools via registry pattern

Installation

Clone and build from source:

git clone https://github.com/dlwiest/ts-tonal-mcp.git
cd ts-tonal-mcp
npm install
npm run build

Configuration

The server requires your Tonal credentials as environment variables:

export TONAL_USERNAME="[email protected]"
export TONAL_PASSWORD="your_password"

Or create a .env file:

[email protected]
TONAL_PASSWORD=your_password

Usage

Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "tonal": {
      "command": "node",
      "args": ["/path/to/ts-tonal-mcp/dist/index.js"],
      "env": {
        "TONAL_USERNAME": "[email protected]",
        "TONAL_PASSWORD": "your_password"
      }
    }
  }
}

Claude Code

Add the server to Claude Code using the CLI:

claude mcp add tonal-mcp node /path/to/ts-tonal-mcp/dist/index.js -e TONAL_USERNAME=your_email -e TONAL_PASSWORD=your_password

Hermes Agent

Put TONAL_USERNAME and TONAL_PASSWORD in ~/.hermes/.env, then register the server under mcp_servers.tonal in ~/.hermes/config.yaml. Values in tools.include are raw tool names such as get_muscle_readiness, never registry names such as mcp__tonal__get_muscle_readiness. Reload the Hermes gateway/MCP connection before expecting new tools in Telegram sessions.

See hermes-tonal for the complete read-only and full-access configurations and companion skill.

Remote (HTTP) Deployment

Set MCP_TRANSPORT=http to serve MCP over Streamable HTTP instead of stdio. The server listens on PORT (default 8080) at /mcp, with a /health endpoint for health checks. MCP_AUTH_TOKEN is required in this mode, and clients must send it as Authorization: Bearer .

MCP_TRANSPORT=http MCP_AUTH_TOKEN=$(openssl rand -hex 32) npm start

Connect from Claude Code:

claude mcp add --transport http tonal https://your-host/mcp --header "Authorization: Bearer "

Direct Usage