AIm Workout Journal MCP server
Commit Nov 12, 2026Lets an AI assistant log workouts, track progress, and provide personalized coaching based on your specific goals, injuries, and lifting history.
Also known as persistmcp/aim, aim
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 1.3.1
- Last commit
- Nov 12, 2026
- License
- MIT
What is AIm Workout Journal MCP?
AIm Workout Journal lets an AI assistant log workouts, track progress, and provide personalized coaching based on your specific goals, injuries, and lifting history.
Summary generated from the project's README
About AIm Workout Journal MCP server
Logging workouts and receiving personalized training advice through an AI assistant is what AIm Workout Journal enables. It functions as an MCP server that connects to a mobile web app, allowing users to describe training sessions in natural language within Claude or ChatGPT. The server provides the assistant with specific data including your fitness goals, injury history, equipment availability, and lifting records to ensure coaching is tailored to your actual physical state rather than generic templates.
Users connect the service using OAuth 2.1 or a specific URL token to link their account. The server exposes 20 tools via FastMCP, including log_session for recording data, get_stats for tracking volume and estimated 1RM, and get_coaching_context to feed the assistant the necessary background for planning. You can also use import_document to upload photos of notebook pages or exports from other trackers. This setup allows your existing AI subscription to act as a dedicated personal trainer that understands your specific progression and physical limitations.
What you can do with it
- 1Log natural language workoutsDescribe a completed gym session in plain English to have it automatically recorded in your history.
- 2Import external training dataUpload a photo of a handwritten notebook page or a file from another app to sync your records.
- 3Generate data-driven coachingAsk your AI assistant to design a new program based on your specific injuries and equipment.
- 4Track strength progressionRequest a summary of your lifting volume and estimated one-rep max improvements over time.
Written from the project's README. Every use case is checked against a quote from it.
How to install AIm Workout Journal MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall AIm Workout Journal MCP in Claude Code
$ claude mcp add --transport http aim https://aim-journal.com/mcpInstall AIm Workout Journal MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"aim": {
"url": "https://aim-journal.com/mcp"
}
}
}Install AIm Workout Journal MCP in VS Code
.vscode/mcp.json
{
"servers": {
"aim": {
"type": "http",
"url": "https://aim-journal.com/mcp"
}
}
}Install AIm Workout Journal MCP in VS Code CLI
$ code --add-mcp '{"name":"aim","type":"http","url":"https://aim-journal.com/mcp"}'Install AIm Workout Journal MCP in Codex
$ codex mcp add aim --url https://aim-journal.com/mcpInstall AIm Workout Journal MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.aim] url = "https://aim-journal.com/mcp"
Install AIm Workout Journal MCP in Gemini CLI
$ gemini mcp add -s user --transport http aim https://aim-journal.com/mcpInstall AIm Workout Journal MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"aim": {
"url": "https://aim-journal.com/mcp",
"type": "http"
}
}
}Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablepersistmcp/aim is public and reachablegithub.com/persistmcp/aim ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-12github.com/persistmcp/aim ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeHTTPS endpoint answered 401 (sign-in required)Pass
README
View on GitHubAIm Workout Journal
A workout tracker your AI assistant writes to. AIm is an MCP server plus a mobile web app (PWA): you describe a session in Claude or ChatGPT in your own words, the assistant logs it through MCP, and the app shows the program, the history, records, estimated 1RM and per muscle load. The server hands the assistant your goal, injuries and logged weights as data, so it plans from your training instead of generic advice.
Live at aim-journal.com. Free, and it runs inside the AI subscription you already pay for rather than being a second one. Guides: connect a workout tracker over MCP, AI personal trainer, 1RM calculator.
How it works
There are two ways in, on the same host, and both resolve to the same user_id:
https://<app>/mcp OAuth 2.1 — add as a connector, approve in the browser
https://<app>/{token} mobile web app / installable PWA
https://<app>/{token}/mcp the original connector address, still supported
https://<app>/{token}/api/* read only JSON the UI consumes
OAuth is what a connector uses now. The server is an OAuth 2.1 resource server: an
unauthenticated call gets a 401 carrying RFC 9728 protected-resource metadata, the client
discovers the authorization server from it, registers itself dynamically, and the user approves on
a consent screen this app serves. Supabase Auth is the authorization server, so no authorization
codes or access tokens are stored here; the access token's sub is mapped to an account through
users.supabase_user_id. Nothing secret is pasted by hand.
The URL token predates it and still works, which is why every link already in someone's inbox
kept working when OAuth landed. A token resolver middleware maps the leading path segment to a user
and scopes every query by user_id; the OAuth path sets the same context variable from a verified
token instead. Two doors, one scoping rule.
What the MCP server exposes
20 tools over stateless streamable HTTP (FastMCP):
- Logging:
log_session,update_session,update_set,delete_session,import_document(paste an export from another tracker or a photo of a notebook page). - Reading:
get_sessions,get_session,get_stats(volume, progression, estimated 1RM via Epley),get_program,get_goals,get_body_metrics. - Catalogue:
search_exercise_pool(a curated global pool with illustrations),list_exercises,upsert_exercise. - Coaching:
get_coaching_contextis the important one. It returns data only: this user's goal, experience, equipment, injuries (with the movement patterns that load them), recent working weights, goal-matched planning ranges and the intake state, for the task at hand (next workout, new program, weekly review), so the assistant plans from data rather than from nothing. How the assistant uses it lives in the server's MCP instructions.review_program_draft,update_coach_profile,upsert_goal,log_coach_event,log_body_metrickeep that context current.
Repo layout
api/index.py Vercel entrypoint (must stay at repo root, see below). Imports backend/src.
requirements.txt Vercel's Python build reads this (must also stay at repo root).
backend/ Python package, tests, scripts, DB migrations.
web/ Vite + React SPA (own package.json, own dev server) and the static guide pages.
api/index.py and requirements.txt cannot move: Vercel's zero config Python builder only
auto detects functions under a root level api/, and only installs a root level
requirements.txt alongside them. Everything else in backend/ (pyproject.toml, uv.lock, tests,
scripts, supabase/) is hidden from the Vercel build by .vercelignore, so Vercel treats the repo
as a static SPA plus one Python function.
One thing to know before you go reading: some code comments cite internal planning documents by
path, such as docs/COACHING_PLAN.md, docs/TEST_CASES.md or docs/DEPLOYMENT.md. Those are
product and research notes that are not published here, so the paths will not resolve. Nothing in
the code depends on them; they are provenance for a decision, not a dependency. Everything you
need to build, test and run what is in this repository is in this README.
Stack
- Backend (
backend/): Python 3.12, FastMCP (stateless HTTP), psycopg3, Supabase Postgres (transaction pooler). MCP and the read API live inbackend/src/workout_storage/, served byapi/index.py. - Frontend (
web/): Vite, React, Tailwind v4, shadcn/ui, recharts, React Query, vite-plugin-pwa. Data layer inweb/src/app/lib/(token to api to adapter to hooks). The guide pages underweb/guides/are generated to static HTML at build time and ship no bundle. - Hosting: one Vercel project.
vercel.jsonroutes mcp, api and cron to the function and everything else to the SPA.
Frontend dev
cd web
npm install
echo 'VITE_API_ORIGIN=https://workout-storage.vercel.app' > .env.local # dev against prod API
npm run dev # http://localhost:5173/{token}
npm run test # vitest: pure function + component tests
npx playwright install chromium # one time, before the first test:e2e run
npm run test:e2e # Playwright, against /demo (no backend needed)
Backend dev
cd backend
uv sync --extra dev # install deps
cp ../.env.example ../.env # fill DATABASE_URL etc. (kept at repo root, shared by all tooling)
uv run pytest # unit + integration + e2e
uv run ruff check . && uv run mypy .
Create a user (prints the token to open in the browser and to paste into an assistant):
cd backend
uv run python scripts/create_user.py --name "Alex"
Running your own
Everything needed is here, but this is the source of a hosted service rather than a turnkey self
host kit: you supply a Supabase project (migrations in backend/supabase/migrations/), a Vercel
project, and the environment variables listed in .env.example. Analytics, email and backup
integrations are optional and stay dormant without their keys.
Attribution
Exercise illustrations are third party works under CC BY-SA, each credited in
web/ATTRIBUTIONS.md. They keep their own license regardless of the license
on this repository.
License
MIT, see LICENSE. The exercise illustrations are the one exception, see Attribution above.
AIm Workout Journal MCP questions
How do I add AIm Workout Journal MCP to Claude Code?
Run claude mcp add --transport http aim https://aim-journal.com/mcp in your terminal. Add --scope user to make it available in every project.
How do I add AIm Workout Journal MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
How does the AI assistant use my data?
The assistant uses the coaching context tool to access your goals, experience, equipment, injuries, and recent weights to plan workouts instead of giving generic advice.
Can I import my existing workout data?
Yes, you can import data by pasting an export from another tracker or by providing a photo of a notebook page.
How do I connect the tracker to my AI assistant?
You can connect via OAuth 2.1 by adding it as a connector and approving it in your browser.