Heart MCP server
Commit Nov 16, 2026Allows an AI client to manage fitness workout logs, records, templates, and exercise programs via a Dart-based backend.
Also known as kit-g/heart-api, heart-api
- Stars
- 1
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 1.0.0
- Last commit
- Nov 16, 2026
- License
- AGPL-3.0
What is Heart MCP?
Heart allows an AI client to manage fitness workout logs, records, templates, and exercise programs via a Dart-based backend.
Summary generated from the project's README
About Heart MCP server
Heart provides a backend interface for managing fitness data within the Heart of Yours application. It allows an AI client to interact with workout logs, exercise records, templates, and structured exercise programs. The system is built on a Dart-based server running on AWS Lambda and uses Supabase for Postgres database management.
Users interact with the server through an API that handles authentication via Firebase OIDC tokens. The architecture includes specialized Python Lambdas for media processing and Firebase push notifications. Because the server relies on AWS services like S3, SQS, and EventBridge, an AI client requires appropriate AWS profiles and database access to function. The backend uses raw SQL instead of an ORM to manage data, ensuring direct control over the Postgres schema through forward-only migrations.
What you can do with it
- 1Update exercise librariesA developer can use the system to sync new exercise data and translations to the Postgres database.
Written from the project's README. Every use case is checked against a quote from it.
How to install Heart MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Heart MCP in Claude Code
$ claude mcp add --transport http heart-api https://mcp.heart-of.me/Install Heart MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"heart-api": {
"url": "https://mcp.heart-of.me/"
}
}
}Install Heart MCP in VS Code
.vscode/mcp.json
{
"servers": {
"heart-api": {
"type": "http",
"url": "https://mcp.heart-of.me/"
}
}
}Install Heart MCP in VS Code CLI
$ code --add-mcp '{"name":"heart-api","type":"http","url":"https://mcp.heart-of.me/"}'Install Heart MCP in Codex
$ codex mcp add heart-api --url https://mcp.heart-of.me/Install Heart MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.heart-api] url = "https://mcp.heart-of.me/"
Install Heart MCP in Gemini CLI
$ gemini mcp add -s user --transport http heart-api https://mcp.heart-of.me/Install Heart MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"heart-api": {
"url": "https://mcp.heart-of.me/",
"type": "http"
}
}
}Automated checks
Ran Nov 14, 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 reachablekit-g/heart-api is public and reachablegithub.com/kit-g/heart-api ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)AGPL-3.0spdx.org/licenses/AGPL-3.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-13github.com/kit-g/heart-api ↗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 GitHubHeart of Yours
Backend for the Heart of Yours fitness app. Dart server on AWS Lambda behind API Gateway, Postgres via Supabase, all CDN/storage on AWS.
Repository layout
heart-go/
├── api/ # Dart server (Lambda entrypoint)
├── shared/
│ ├── heart_models/ # Data classes + service interfaces (used by api + the Flutter client)
│ └── heart_aws/ # Boto3-shaped AWS clients (S3, SQS, SNS, Scheduler) on aws_signature_v4
├── database/
│ ├── migrations/ # Forward-only SQL migrations
│ ├── tests/ # pgtap suite — public/{tables,functions}, archive/...
│ └── test_utils/ # Test helpers (builders + JSON validators)
├── firebase/ # Python Lambda: FCM push + Firebase auth cleanup (uv workspace member)
├── assets/ # Python Lambda: exercise media processing pipeline (uv workspace member)
├── infrastructure/ # Terraform stacks (api, assets, cdn, content, firebase, monitoring)
│ # + environments/{dev,prod} — see infrastructure/README.md
├── content/ # Exercise library YAML + schema + sample templates JSON, synced to CDN
├── scripts/ # Migration runner, db test runner, library sync/validation
├── site/ # Static marketing/legal pages
├── docs/ # Dated design docs; handoff.md is the definition of done, style.md the house style
├── agents/ # Autonomous agent launchers + guard hook (see agents/README.md)
└── .github/workflows/ # CI: deploy-api, deploy-assets, deploy-firebase, exercise-library
# (each split into a reusable workflow + dev/prod wrappers)
Per-component docs:
- api/README.md — server architecture, routing/db/AWS conventions, testing
- database/README.md — migrations + pgtap
- infrastructure/README.md — Terraform stacks + deployment
Stack
| Layer | Tech |
|---|---|
| Server runtime | Dart 3.10 + relic, compiled to native + Lambda Web Adapter |
| Storage | Postgres (Supabase), no ORM — raw SQL |
| Object storage / CDN | S3 + CloudFront |
| Auth | Firebase OIDC token verification |
| Async | EventBridge S3-rules → SQS → /events (Lambda routes events back to itself) |
| Scheduled jobs | EventBridge Scheduler → SQS → /events |
| Side services | Python 3.13 Lambdas in a uv workspace: firebase/ (push, auth cleanup), assets/ (media) |
| IaC | Terraform (with Supabase provider) |
| CI/CD | GitHub Actions, OIDC role for AWS |
| Tests | Dart test + mockito for app code, pgtap for the database, pytest for the Python services |
Local development
make bootstrap # dart pub get + mocks for all packages, uv sync, git hooks
make db-up # containerized Postgres 17 + pgtap (skip if you run a native one)
make test # the full matrix: Dart x3, migrations + pgtap, pytest x3
make lint # dart analyze x3 + ruff
Each suite can also run individually — make test-dart / test-db / test-python,
or the underlying commands directly (see the Makefile and per-component READMEs).
The api package can be run locally against any Postgres + AWS profile — see api/README.md.
Deployment
Every workflow family is a reusable workflow plus thin -dev / -prod wrappers. Dev ships from
main pushes. Prod: api and exercise-library ship from v* tags; assets and firebase prod
deploys are currently manual (workflow_dispatch). Pull requests run the test jobs only — the
deploy jobs are gated on the event type.
deploy-api.yml (api/shared/database changes):
- Lint, format check, analyze
- Dart tests across all three packages
- Database tests: ephemeral Postgres + pgtap via
scripts/db_tests.sh, then the full api suite (includingdb-tagged integration tests) with a coverage floor - Apply unapplied migrations to Supabase
- Build Lambda binary, update function, smoke-test
/version
deploy-firebase.yml / deploy-assets.yml (Python changes): pytest, then package and update the
function code.
exercise-library.yml (content changes): validate the library YAML against its JSON schema plus
the sync parser, then sync exercises + translations to Postgres (guarded against mass-archiving).
Conventions
- Migrations are forward-only. No down migrations. Wrong schema → write a new migration that fixes it.
- No comments unless the WHY is non-obvious — naming carries the WHAT.
- Single source of truth for shapes. Anything the client sees lives in
heart_models; server-only types stay inapi/lib/models. - Boto3-shaped AWS package — generic, no domain knowledge in
heart_aws.
Licence
The server and everything else in this repository is under the
GNU AGPL v3.0. The shared packages (shared/heart_models, shared/heart_aws,
shared/heart_design) are under the Apache License 2.0, and the
exercise library and other content in content/ under CC BY 4.0.
The name and logo aren't covered by any of them. NOTICE has the full map, including
what in the repository isn't ours. The reasons are in
docs/2026-10-24.licence.md.
Contributing
Contributions come in under the licence of the directory they change (inbound = outbound): AGPL
for the server, Apache-2.0 for the shared packages, CC BY 4.0 for content/. Opening a pull
request means you agree to that and that the work is yours to give. There is no CLA.
Heart MCP questions
How do I add Heart MCP to Claude Code?
Run claude mcp add --transport http heart-api https://mcp.heart-of.me/ in your terminal. Add --scope user to make it available in every project.
How do I add Heart MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What technologies are used for the database?
The server uses Postgres via Supabase and utilizes raw SQL instead of an ORM.
How is authentication handled?
The system uses Firebase OIDC token verification for authentication.