The aiTrainer server acts as a personal workout coach, allowing you to log, track, and manage exercise data through an MCP interface.
Log workouts: Record exercises with sets, reps, weights, optional RPE (1–10), notes, and units; automatically grouped into sessions based on the day and idle timeout.
View current workout: Retrieve the open workout session and all exercises logged so far today.
Exercise history: Get recent workout sessions for a specific exercise to review past performance.
Recent workouts: Browse workout sessions across all exercises, filterable by number of days or result limit.
Progress & coaching signals: Obtain insights for a specific exercise including estimated 1RM, personal bests, volume trends, and sessions since last weight increase.
List exercises: View known exercises and their aliases (e.g. bench, bench press) to help normalize names when logging.
Edit sessions and sets: Fetch a session by ID, update session dates/notes, or modify individual sets by ID.
Delete data: Remove entire workout sessions or specific exercises from a session.
Allows logging exercises and reading workout progress via Telegram chat.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@aiTrainer Log squat 5 reps at 100 kg"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Personal workout coach as a Python MCP server for OpenClaw. Chat over Telegram, log exercises in natural language, and let the agent read structured progress from SQLite.
Log exercises, sets, reps, weights, optional RPE, and notes
Automatic workout session grouping (same day + within idle timeout)
Exercise aliases (bench, bench press, etc.)
Progress signals: estimated 1RM, personal bests, volume trend, sessions since last increase
MCP stdio transport for OpenClaw
Related MCP server: super-hevy-mcp
Python 3.11+
Linux target machine (also works on macOS for development)
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"aicoach-mcpOr:
python -m aicoach.serverEnvironment variables:
Variable | Default | Description |
|
| SQLite database path |
|
| Default weight unit |
|
| Auto-close idle workout sessions |
Add aiCoach to your OpenClaw MCP config. On a standard install this lives in ~/.openclaw/openclaw.json.
openclaw mcp set aicoach '{
"command": "/path/to/aicoach/.venv/bin/aicoach-mcp",
"env": {
"AICOACH_DB_PATH": "/home/you/.local/share/aicoach/aicoach.db"
}
}'{
"mcpServers": {
"aicoach": {
"command": "/path/to/aicoach/.venv/bin/aicoach-mcp",
"args": [],
"env": {
"AICOACH_DB_PATH": "/home/you/.local/share/aicoach/aicoach.db"
}
}
}
}Notes:
A command field means OpenClaw launches the server over stdio automatically.
Use the absolute path to your virtualenv binary on the Linux host.
Restart or reload OpenClaw after changing MCP config.
Copy prompts/coach_instructions.md into your OpenClaw agent instructions so the model knows when to call aiCoach tools.
Tool | Purpose |
| Log one exercise and attach it to the current session |
| Show the open session and exercises logged so far |
| Fetch one session with set ids for editing |
| Recent sessions for one exercise |
| Recent sessions across exercises |
| Coaching signals for one exercise |
| Known exercises and aliases |
| Change a session date or note |
| Update one set by id |
| Delete an entire workout session |
| Delete one exercise from a session |
| Merge source sessions into one target session |
{
"exercise": "squat",
"sets": [
{"reps": 5, "weight": 100},
{"reps": 5, "weight": 100},
{"reps": 5, "weight": 100}
],
"note": "moved well"
}pytestMCP stdio smoke test:
python scripts/mcp_smoke_test.pySee examples/openclaw-mcp-snippet.json for a copy-paste MCP server entry.
aicoach/
config.py # settings and env vars
db.py # sqlite schema
repository.py # storage and session logic
progress.py # coaching signals
server.py # MCP server
prompts/
coach_instructions.md
tests/Return the open workout session and all exercises logged so far today.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description adequately states 'returns' but does not disclose behavior when no open session exists or if multiple exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single clear sentence with no redundant information, front-loaded purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no parameters and an output schema existing, the description fully explains what the tool returns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters in schema, so description does not need to add param info; baseline score of 4 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns the open workout session and exercises logged today, distinguishing it from siblings like get_exercise_history and log_workout.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implied usage for retrieving current workout, but no explicit guidance on when not to use or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return recent workout sessions for a single exercise.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| exercise | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It only says 'Return', implying read-only, but does not explicitly confirm non-destructiveness, mention authorization needs, or define 'recent' (e.g., time window or number of sessions). This leaves significant gaps for an agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-formed sentence with no wasted words. However, it is slightly too brief to cover important aspects, but conciseness is appropriately high for what it offers.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (2 parameters, simple types) and the presence of an output schema, the description is minimally viable. But it lacks details on ordering, time range, or default behavior (e.g., 'recent' implies last N sessions, but N is default 10). It is adequate but has clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description should add meaning. It mentions 'for a single exercise' but does not explain the 'exercise' parameter's format or values, and ignores the 'limit' parameter entirely. The description adds minimal semantic value beyond the parameter names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns recent workout sessions for a single exercise, using specific verb 'Return' and resource 'workout sessions for a single exercise'. This distinguishes it from siblings like get_recent_workouts (likely for all exercises) and get_current_workout.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, no prerequisites, and no context on usage scenarios. It is a minimal statement without any usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return coaching signals such as estimated 1RM, volume trend, and PRs.
| Name | Required | Description | Default |
|---|---|---|---|
| exercise | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist; the description only states it returns data but lacks details on auth requirements, error handling, or output format, leaving the agent with minimal behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no fluff, but could be slightly more informative without losing conciseness. Loses a point for being too minimal.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Missing key context like whether progress is for a single exercise or all, the exact nature of 'coaching signals,' and how the output relates to the input parameter, despite having an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter 'exercise' has no description in schema and the tool description does not explicitly state that progress is per exercise; it only implies through examples. With 0% schema coverage, the description should compensate but does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Return coaching signals' with specific examples (1RM, volume trend, PRs), and the verb+resource is distinct from sibling tools like get_exercise_history or get_current_workout.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage when progress data is needed, but no explicit guidelines on when to use this vs. siblings or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return recent workout sessions across all exercises.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | ||
| limit | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It does not mention ordering, read-only nature, privacy, or data freshness. Minimal behavioral context beyond basic output.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence is concise but omits critical information. Conciseness alone does not compensate for lack of utility.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, description fails to clarify parameter semantics or behavioral context. Agent cannot reliably invoke the tool without assumptions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and description adds no explanation for parameters 'days' or 'limit'. Agent cannot infer their meaning or constraints without additional context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'return recent workout sessions across all exercises', specifying verb and resource. It distinguishes from sibling tools like get_current_workout and get_exercise_history, but 'recent' is vague without a time range.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. Agent must infer usage from context signals alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List known exercises and aliases to help normalize exercise names.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It only states the action (list) and purpose, but does not disclose read-only nature, auth needs, rate limits, or any side effects. Output schema exists but is not described.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no wasted words. It is front-loaded and efficient, earning its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no parameters and an output schema, the description is adequate but lacks behavioral transparency and usage guidelines. It fulfills the basic purpose but leaves gaps for an agent to infer safety and context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, and schema coverage is 100% by default. According to rules, 0 params yields a baseline of 4; the description does not need to add parameter info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a clear verb 'list' and resource 'known exercises and aliases', with a specific purpose 'help normalize exercise names'. It distinguishes from sibling tools like get_exercise_history or get_current_workout.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, or any prerequisites. The purpose implies lookup, but no explicit when/when-not context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Log sets for one exercise and attach them to the current open workout session.
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | ||
| sets | Yes | ||
| exercise | Yes | ||
| performed_on | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description discloses core action (attaching sets to current workout) but lacks details on error handling, idempotency, or side effects if no session exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence of 12 words, no redundancy, clearly front-loads action and context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists so return values are handled. Description covers main purpose but misses usage prerequisites and behavioral constraints.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% (description doesn't mention parameters), but schema itself provides parameter descriptions (e.g., reps, weight). Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'log', resource 'sets for one exercise', and context 'attach to current open workout session'. Distinguishes from sibling tools like get_current_workout or list_exercises.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives. Does not mention prerequisites (e.g., need an open workout session) or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0get_current_workoutget_exercise_historyget_progressget_recent_workoutslist_exerciseslog_workoutScored across 6 tools
Each tool targets a distinct aspect: current workout, exercise history, progress, recent workouts, exercise list, and logging. No overlap in purpose.
Every tool follows a consistent verb_noun pattern (get_, list_, log_), with no mixing of styles or vague verbs.
With 6 tools, the server is well-scoped for a workout tracking assistant—not too few, not too many.
Covers core needs: listing exercises, logging, viewing current workout, history, and progress. Minor gap: no explicit create/close session, though log_workout may implicitly open one.
Log workouts and meals by telling your AI. 873 exercises, muscle diagrams, food lookup.
Agent-first strength-training platform across iOS, Web & MCP: read & write workouts, PRs & plans.
Private Apple Health metrics and workout detail for ChatGPT, Claude, and any MCP client.
GibsonAI MCP server: manage your databases with natural language
