JustGains MCP server

JustGains MCP server

The official JustGains MCP server. It lets an AI agent build and save workouts, read a person's training history and progress, search the JustGains exercise library, plan routes, and log meals and bodyweight in their JustGains account.

There are two ways to run it: connect to the hosted server (nothing to install), or run the stdio server in mcp-server/ on your own machine.

Connect to the hosted server

Add it as a remote MCP server and complete the browser sign-in with the JustGains account you use on your phone. An unauthenticated request returns 401 with a WWW-Authenticate challenge, so MCP clients start the sign-in on their own. Authentication uses the authorization code flow with PKCE S256, dynamic client registration, and the workouts progress profile scopes. No API key is needed and no credentials are stored in this repository.

Claude Code:

claude mcp add --transport http justgains https://justgains.com/connect/mcp

Cursor and other clients that read an mcpServers file:

{
  "mcpServers": {
    "justgains": {
      "url": "https://justgains.com/connect/mcp"
    }
  }
}

Grok Bot and Cursor plugin

This repository is also the JustGains plugin for Grok Bot and Cursor (.cursor-plugin/plugin.json, mcp.json, .mcp.json), which connects to https://justgains.com/grok/mcp, the same server and tools. In Grok Bot, open Marketplace, find JustGains when its listing is available, and choose Add, then complete the JustGains authorization in your browser. Mention JustGains with @ in a conversation to use it. Marketplace listing requires review; publishing this repository does not mean the listing has been approved. Where custom MCP servers are allowed, add a Remote HTTPS server with either URL. Team policies may restrict custom servers.

Run it locally (stdio)

mcp-server/ is a stdio MCP server written in TypeScript on the official MCP SDK. It serves the live JustGains tool catalog, so its schemas always match the hosted server, and executes each call through the JustGains tool API as the signed-in user. It needs Bun.

git clone https://github.com/JustGains/justgains-connector.git
cd justgains-connector/mcp-server
bun install
bun run login   # opens the JustGains sign-in in your browser

login runs the same OAuth flow as the hosted server with a loopback redirect and stores the rotating refresh token in ~/.justgains/mcp-credentials.json. Without signing in, the public tools (exercise search, workout generation and previews) still work. Then point your client at the server:

{
  "mcpServers": {
    "justgains": {
      "command": "bun",
      "args": ["run", "/path/to/justgains-connector/mcp-server/src/index.ts"]
    }
  }
}

The Dockerfile builds and runs the same stdio server.

Tools

Tools marked "account" need a signed-in user. Every tool declares its read-only, destructive and open-world hints.

Workouts

Shortened. The full README is on GitHub.