Provides access to Matrix / Johnson Fitness ride history, allowing agents to list workouts, retrieve full ride details and 10-second sample series, summarize volume and power curves, compare workouts, and export ride data.
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., "@matrix-workouts-mcp what was my best 5-minute power this month, and which ride was it?"
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.
An MCP server for your Matrix / Johnson Fitness ride history, so an AI agent can answer questions about it.
The dashboard at matrixworkouts.jfit.co shows six numbers per ride. The record
behind it carries a sample every 10 seconds with power (watts), console resistance
level and cadence (rpm) — none of which appears anywhere in the site's UI, and none
of which its own list page can reach for anything older than about a week. This server
hands all of it to an agent, with the cross-ride views the platform has never had:
power curve, training volume by week or month, one ride against another.
> what was my best 5-minute power this month, and which ride was it?
> compare my last two Sprint 8 sessions
> has my average power at resistance 8 moved since August?claude mcp add matrix-workouts -- npx -y matrix-workouts-mcpOr, in a client that takes JSON:
{
"mcpServers": {
"matrix-workouts": {
"command": "npx",
"args": ["-y", "matrix-workouts-mcp"],
"env": {
"MATRIX_XID": "your-member-number",
"MATRIX_PIN": "your-passcode"
}
}
}
}Node 20 or newer.
You can also run it without credentials. Download your history once with
npx matrix-workouts-history,
point MATRIX_CACHE_DIR at the result, and every tool except refresh_history works
against it. No passcode in a config file, no sign-in from the server at all.
Related MCP server: Iridium MCP Server
Variable | Default | What it does |
| — | Member number from the gym tag. Without it the server is read-only over the cache. |
| — | Numeric passcode. Used for one sign-in request, never stored or logged. |
|
| Where the downloaded history is kept, written |
|
| How long a cached history is served before a refetch. |
|
| Set to |
|
| HTTP transport only. |
|
| HTTP transport only. Loopback on purpose — see Privacy. |
| — | Bearer token. Required for the HTTP transport; the server refuses to start without it. |
Tool | Returns |
| Rides newest first, one compact row each. Filter by date, machine or program mode. No sample series. |
| One ride in full: work, power, cadence, resistance, both heart-rate averages, and what the console was holding constant. |
| The 10-second interval series as CSV, over a window and a stride you choose. |
| Volume by week or month, plus the power curve over the matched rides. |
| Two to eight rides side by side on every derived number. |
| Writes a lossless JSON export document and returns the path. |
| Re-downloads from the API. Needs credentials. |
Tools answer from one cached history rather than fetching per call — the API returns every ride on the account in a single response, so anything else would re-download your entire history a dozen times a conversation.
Two heart-rate averages, always. The platform's own figure is not derived from the sample series and does not always agree with it: the console averages in real time, ahead of the dropouts the series preserves. On a glitching strap the reported figure is the better one — on one ride with independent Apple Watch ground truth, the console's 153 bpm was exactly right and the filtered series gave 151. Reporting only ours would be quietly misleading, so both go out, labelled.
This is your heart rate at ten-second resolution, and handing it to a language model is a real decision rather than a formality. What the server does about that:
The HTTP transport refuses to start without MATRIX_MCP_TOKEN, and binds
127.0.0.1 unless you deliberately change it. Over stdio nothing is listening at
all, which is the mode to prefer.
Credentials are used for one sign-in request. The passcode is never stored, logged or returned; the bearer token is never persisted. Errors from the API client are redacted before they can carry a token into a message.
Cached and exported files are written 0600, outside any repository.
export_workout returns a path, never the contents — partly for your context
budget, mostly because a document is a thing you keep rather than a thing you paste.
Nothing is sent anywhere but apollo.jfit.co, the API the data came from.
Running with no credentials at all, over a cache you downloaded yourself, is the
tightest configuration and everything except refresh_history still works.
npm test # vitest, against real ride fixtures — no network
npm run typecheck
npm run build
npm run dev # tsx src/cli.tsTests use three real captured rides and a stubbed downloader, so the suite needs
neither credentials nor a network. src/docs.test.ts fails the build if a tool or an
environment variable is missing from the tables above — see AGENTS.md.
Cutting a release:
npm run release -- patch # bumps, tags, packs; refuses without a CHANGELOG entry
git push origin main:main --follow-tags
npm publish --access publicthe parser, API client and export format this is built on | |
a Chrome extension that puts the same data on screen | |
this server |
MIT licensed. Unaffiliated with Matrix Fitness or Johnson Health Tech.
Two or more rides side by side on every derived number. Use it for 'how did today compare to last Tuesday' rather than calling get_workout repeatedly.
| Name | Required | Description | Default |
|---|---|---|---|
| ids | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It implies comparison but does not state side effects, performance, output shape, or limitations. The 'derived number' phrase is ambiguous and adds little behavioral clarity.
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 short and front-loads the core concept, with a usage example embedded. It is concise, though the phrase 'every derived number' is odd and slightly wastes the second sentence's potential.
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 one parameter and no annotations or output schema, the description leaves key details missing: what 'ids' means, what comparison metrics are returned, and any constraints. The guidance to avoid get_workout is helpful but insufficient.
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 coverage is 0% and the description does not explain the 'ids' parameter beyond the schema. It does not clarify expected IDs, count limits, or formatting, so the description fails to compensate for the lack of schema documentation.
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 'Two or more rides side by side on every derived number' conveys a compare action with specific intent, but 'derived number' is vague and doesn't clearly state what is compared (e.g., metrics, workouts). It does distinguish from siblings by advising not to call get_workout repeatedly.
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?
Provides a concrete use case ('how did today compare to last Tuesday') and explicitly contrasts with an alternative ('rather than calling get_workout repeatedly'). It lacks when-not-to-use or other alternatives, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write one ride to disk as a lossless JSON export document — normalized telemetry plus the upstream record verbatim. Returns the path, not the contents, because the document is far too large to read into a conversation.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| path | No | Directory or file path. Defaults to the cache directory. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the disclosure burden. It clearly reveals that the tool writes to disk, returns a path rather than file contents, and explains the size rationale. It could add details about overwrite behavior or file naming, but the core side effects and output behavior are well disclosed.
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?
Two tight sentences, front-loaded with the action and format, then a concrete behavioral clarification. Every sentence earns its place with no filler.
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?
The tool is simple, but with no output schema the description must explain return value and side effects, which it does by stating a path is returned and contents are intentionally omitted. Minor gaps remain around output file naming/extension and overwrite semantics, but an agent has enough to call it correctly.
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 only 50%, and the tool description does not compensate. The 'id' parameter is only typed as a string with no explanation, and although the description mentions 'one ride', it never explicitly maps that to the id parameter. The 'path' parameter is already explained in the schema and gains no extra meaning.
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 states a specific action ('write one ride to disk'), a concrete resource outcome ('lossless JSON export document'), and the document's composition. It clearly differentiates from siblings like get_workout by explicitly saying it returns the path, not the contents.
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 implies the tool is for persisting a workout for later use and that it should not be used when contents are needed in conversation. However, it does not explicitly name an alternative tool or state when-not-to-use conditions, leaving routing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The raw interval series for one ride as CSV — power, cadence, resistance, heart rate, speed, one row per 10 seconds. Ask for a window and a stride rather than a whole ride: a full ride is several hundred rows.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| fields | No | Default: power, cadence, resistance, heartRate. | |
| maxRows | No | Default 200. | |
| everyNth | No | Stride; 6 gives one row per minute. | |
| toSeconds | No | ||
| fromSeconds | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the data granularity (one row per 10 seconds), the output format (CSV), and the volume concern (full ride is several hundred rows). It does not mention default parameter behavior, error handling, or any rate/performance implications beyond the size hint. It adds some context but is not comprehensive.
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 two sentences with no wasted words. The first sentence front-loads the purpose and output format; the second gives actionable usage guidance. Every sentence earns 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 data retrieval tool with no output schema and no annotations, the description covers the essential aspects: what it returns, the granularity, the size concern, and how to limit the request. It could mention defaults for parameters (though the schema covers those) and clarify that the output is a CSV string, but it is sufficiently complete for an agent to call it correctly.
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 50% – only fields, maxRows, and everyNth have descriptions. The description adds meaning for the undocumented window parameters by referencing 'a window' (fromSeconds/toSeconds) and 'a stride' (everyNth), clarifying their intended use. It also lists the field names, reinforcing the fields enum. This compensates for the schema gap, though it does not explicitly explain id or maxRows beyond what schema already states.
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's function: 'raw interval series for one ride as CSV' and enumerates the specific data columns (power, cadence, resistance, heart rate, speed). It also notes the row granularity (one row per 10 seconds). This is a specific verb-resource pairing that distinguishes it from siblings like get_workout (summary) and export_workout (likely a different format).
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 gives clear usage advice on how to call the tool: 'Ask for a window and a stride rather than a whole ride' and notes the size concern. However, it does not explicitly state when to use this tool versus alternatives like get_workout or export_workout. The guidance is on parameter selection rather than tool selection, so it is implied usage rather than explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Everything derived about one ride: duration, distance, work done, average and peak power, cadence, resistance, both heart-rate averages, and what the console was actually holding constant. Does not return the sample series — use get_samples for that.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Workout id, from list_workouts. Either id form works. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of disclosing behavior. It transparently lists what the tool returns and what it excludes, adding context beyond the schema. It does not mention side effects, error handling, or explicit read-only status, but as a 'get' operation, these are less critical. The description adds value by enumerating the exact fields and the exclusion, which is a solid behavioral disclosure for a simple retrieval tool.
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 concise—two sentences—with no filler. It front-loads the content list and immediately follows with the exclusion and alternative. Every sentence earns its place, and the structure is clear and direct.
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 single-parameter get tool, the description is complete: it enumerates all returned fields, specifies the key exclusion, and references the alternative tool. It does not need an output schema because the fields are listed. The only minor ambiguity is the phrase 'what the console was actually holding constant,' but this is a specific field name and does not hinder correct invocation.
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 schema already provides 100% coverage for the single parameter 'id' with a clear description ('Workout id, from list_workouts. Either id form works.'). The tool description does not add any additional parameter semantics beyond what the schema already states, so the baseline of 3 is appropriate per the rubric.
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 a comprehensive set of derived metrics for a single ride (duration, distance, power, cadence, resistance, heart-rate averages, and a console constant). It uses a specific verb and resource, and explicitly distinguishes itself from get_samples by noting it does not return sample series. This leaves no ambiguity about what the tool does.
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 explicitly tells the agent when not to use this tool and directs it to the alternative: 'Does not return the sample series — use get_samples for that.' This is a clear exclusion and recommendation. It also implies usage for obtaining summary stats, while the sibling list_workouts is implied for obtaining IDs. This provides sufficient routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List recorded rides, newest first, one compact row each: date, program mode, duration, distance, average power and heart rate. Use this first to find the id of a ride before asking for its detail. Returns no sample series.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | Inclusive end date, YYYY-MM-DD. | |
| from | No | Inclusive start date, YYYY-MM-DD. | |
| mode | No | Program mode, e.g. sprint_8, target_heart_rate. | |
| limit | No | Default 20. | |
| machineType | No | e.g. upright_bike, recumbent_bike. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It discloses ordering, output shape, and the absence of sample series, which gives an agent a solid mental model of the result. It does not explicitly state read-only behavior, but 'List' reasonably implies it.
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?
Three sentences, each earning its place: the first states what is returned, the second explains the primary use case, and the third sets expectations about a sibling feature. The most important information is front-loaded.
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 there is no output schema, the description compensates by enumerating the row fields, ordering, and the absence of sample series. It could mention pagination or limit behavior, but those are already covered by the schema's parameter descriptions.
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 100%, so the schema already documents all five parameters with types and examples. The description adds little parameter-level semantics beyond the schema, which matches the baseline for high coverage.
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 specific verb and resource: 'List recorded rides' with explicit ordering ('newest first') and a precise summary of each row's contents. It clearly differentiates from siblings by noting 'Returns no sample series,' separating it from get_samples and get_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?
It explicitly instructs when to use the tool: 'Use this first to find the id of a ride before asking for its detail,' routing the agent to the detail sibling. It also provides an exclusion by stating it returns no sample series, which directs agents away from using it for sample data.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Re-download the whole history from the API, replacing the cache. Needs credentials. Everything else answers from the cache, so call this only when a ride is missing because it happened since the last fetch.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses that the operation replaces the cache (destructive), requires credentials, and is not for routine queries. It does not mention rate limits or response format, but for a no-parameter tool, these are minor omissions.
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 two sentences with no redundancy. The core action is front-loaded ('Re-download the whole history'), followed by necessary conditions and usage guidance. Every word adds value.
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 no parameters, no output schema, and no annotations, the description fully covers purpose, usage, and behavior. It tells the agent exactly when to invoke it, what it does, and what it requires. Nothing essential is missing for safe and correct invocation.
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?
There are zero parameters, so the baseline is 4. The description correctly avoids explaining any parameters since none exist. No additional parameter context is needed.
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 re-downloads the entire history from the API and replaces the cache. This specific verb-resource pairing differentiates it from siblings that answer from cache, making the purpose unmistakable.
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?
It explicitly states when to call this tool: 'only when a ride is missing because it happened since the last fetch.' This gives a clear condition and implies that for other queries, the cache-based tools should be used. The guidance is direct and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Training volume per week or month — rides, time, distance, work, average power and heart rate — plus the all-time power curve over the matched rides. This is the tool for questions about trends, totals and bests.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | Inclusive end date, YYYY-MM-DD. | |
| from | No | Inclusive start date, YYYY-MM-DD. | |
| bucket | No | Default month. | |
| windowsSeconds | No | Power-curve durations. Default 10, 30, 60, 300, 600, 1200, 3600. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the behavioral burden. It does disclose aggregation behavior and the output metrics, including the all-time power curve over matched rides. However, it does not state whether the operation is read-only, how 'matched rides' are determined, or what the overall response shape looks like.
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 two sentences with no filler, and the core capability is front-loaded. The long em-dash list makes it slightly dense, but every part earns 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?
Without annotations or an output schema, the description provides a solid summary of outputs but omits operational context such as the meaning of 'matched rides' relative to the date range, default bucket/window behavior, and whether refresh_history is a prerequisite. Parameter details are covered by the schema, but the tool-level context is only partially complete.
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 100%, so the schema already documents all four parameters. The description reinforces the connection to bucket (week/month) and windowsSeconds (power-curve durations), but adds no meaning beyond what the schema already provides.
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 identifies the resource (training history), the aggregation granularity (week/month), and the specific metrics returned (rides, time, distance, work, average power, heart rate, power curve). It lacks an explicit verb like 'summarizes' and does not explicitly contrast with sibling compare_workouts, but the scope is unambiguous.
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 sentence 'This is the tool for questions about trends, totals and bests' gives the agent a clear signal about when to select this tool. It does not mention exclusions or name alternative sibling tools, so it stops short of full routing guidance.
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.0compare_workoutsexport_workoutget_samplesget_workoutlist_workoutsrefresh_historysummarize_historyScored across 7 tools
Each tool targets a distinct operation—listing, single-ride detail, raw samples, aggregates, comparison, export, and cache refresh—and the descriptions explicitly cross-reference the intended usage. No two tools overlap in function, and boundary cases like get_workout vs get_samples are clearly called out.
All seven tools follow a consistent verb_noun snake_case pattern (list_, get_, summarize_, compare_, export_, refresh_). Singular and plural noun usage is logical and predictable, making tool selection straightforward.
Seven tools is well-scoped for a workout-history MCP: the core read, analyze, and export paths are covered without redundancy. Each tool earns its place, and there is no sense of bloat or thinness.
The surface covers listing, detail, raw samples, aggregation, comparison, export, and cache refresh, so a user can go from finding a ride to analyzing or exporting it without dead ends. Create/update/delete are not needed because the server reads externally recorded rides and refresh_history handles new data.
AI cycling coach: training plans, workouts, nutrition, strength training, Strava, Garmin and Wahoo.
Private Apple Health metrics and workout detail for ChatGPT, Claude, and any MCP client.
Read your workouts, history, and stats; create and schedule new workouts. Writes are additive only.
Connect Claude to your Intervals.icu watch data for fitness, workout review, and plan writing.
