Skip to main content
Glama
My Gym Stats MCP

My Gym Stats MCP

README.md
# My Gym Stats MCP

I love working out, and I have kept a logbook since I started training. It tracks my progress, including the weight lifted and the number of sets and repetitions performed.

The logbook is stored in Google Drive as a collection of Google Sheets. Each spreadsheet covers one month, with a separate tab for every training session.

This project makes that data accessible to an LLM client—ChatGPT, in my case. The client sends requests to a Node.js MCP server, which reads the logbook through the Google Sheets API and returns the requested information.

A concrete example of the resulting output is shown in [this image](img/results.png).

<p align="center">
  <img src="img/architecture-overview.svg" alt="My Gym Stats MCP architecture and message flow" width="100%">
</p>

## Tech Stack

| Technology                       | Role                                                |
| -------------------------------- | --------------------------------------------------- |
| **Node.js**                      | Server runtime                                      |
| **TypeScript**                   | Type-safe application code                          |
| **Model Context Protocol (MCP)** | Communication between the LLM client and the server |
| **Google Drive API**             | Restricted discovery of logbook files               |
| **Google Sheets API**            | Access to workout data stored in Google Sheets      |
| **JSON-RPC**                     | Message format used by MCP                          |

## Configuration

1. Enable both the Google Drive API and Google Sheets API in your Google Cloud project.
2. Configure [Application Default Credentials](https://cloud.google.com/docs/authentication/application-default-credentials). If you use a service account, share only the `logbook` folder with its email address.
3. Copy `.env.example` to `.env` and set:
   - `GOOGLE_APPLICATION_CREDENTIALS` to the absolute path of the credentials file.
   - `GOOGLE_DRIVE_LOGBOOK_FOLDER_ID` to the ID from the `logbook` folder URL.

All tools are read-only. Starting from the configured `logbook` folder, the server discovers only direct child folders named `YYYY` and only their direct Google Spreadsheet children. Callers cannot provide paths, file IDs, URLs, or cell ranges.

## Tools

| Tool | Purpose | Input |
| --- | --- | --- |
| `list_logbook_files` | List the available monthly spreadsheets without reading their cells | None |
| `read_logbook_month` | Read every worksheet for one month | `year`, `month` |
| `read_logbook_year` | Read every monthly spreadsheet for one year | `year` |
| `read_entire_logbook` | Read all valid monthly spreadsheets across every year | None |

The reading tools use the `spreadsheets.readonly` scope. A single response is limited to 250,000 populated cells and 4,000,000 serialized characters.

## How to run

```bash
nvm use
npm i
npm run build
npm run dev # runs the MCP server
npm run inspector # run in a separate shell
```

## How to use with ChatGPT

This server can be connected to ChatGPT through an OpenAI [Secure MCP Tunnel](https://developers.openai.com/api/docs/guides/secure-mcp-tunnels), without exposing the local MCP server to the public internet.

### 1. Prepare the project

Complete the [Configuration](#configuration) steps, then install the dependencies and build the server:

```bash
nvm use
npm install
npm run build
```

### 2. Create an OpenAI tunnel

1. Open the [OpenAI Platform tunnel settings](https://platform.openai.com/settings/organization/tunnels).
2. Create a tunnel and associate it with the ChatGPT workspace that will use it.
3. Copy its `tunnel_id`.
4. Create a runtime API key with **Tunnels Read + Use** permission. Creating or editing the tunnel also requires **Tunnels Read + Manage**.
5. Download and install the latest `tunnel-client` release linked from the tunnel settings page.

Keep the API key private. Load it into the shell used to run the tunnel client:

```bash
export CONTROL_PLANE_API_KEY="sk-..."
```

### 3. Configure the tunnel client

Replace the example tunnel ID and both project paths with your own absolute values:

```bash
tunnel-client init \
  --sample sample_mcp_stdio_local \
  --profile my-gym-stats \
  --tunnel-id tunnel_0123456789abcdef0123456789abcdef \
  --mcp-command "node --env-file=/absolute/path/to/my-gym-stats-mcp/.env /absolute/path/to/my-gym-stats-mcp/dist/index.js"
```

Validate the profile before starting it:

```bash
tunnel-client doctor --profile my-gym-stats --explain
```

### 4. Start the tunnel

```bash
tunnel-client run --profile my-gym-stats
```

Keep this process running while using the plugin. The tunnel client starts the MCP server itself, so `npm run dev` or `npm start` does not need to run separately.

### 5. Add the MCP server to ChatGPT

1. Open [ChatGPT Plugins](https://chatgpt.com/#settings/Connectors).
2. Select the plus button, then **Add custom MCP server**.
3. Enter a name such as `My Gym Stats`.
4. Under **Connection**, select **Tunnel**, then select the tunnel or paste its `tunnel_id`.
5. Select **No authentication**. Authentication to Google is handled locally by the server credentials configured in `.env`.
6. Review the security warning, select **I understand and want to continue**, and create the plugin.
7. Install the plugin in your personal plugins or the intended workspace.

In a conversation, type `@My Gym Stats` and ask ChatGPT to use one of the available tools. For example:

> Use My Gym Stats to read March 2025 and summarize my training sessions.

If ChatGPT cannot discover or call the tools, confirm that `tunnel-client run` is still active and rerun:

```bash
tunnel-client doctor --profile my-gym-stats --explain
```

After changing tool names, descriptions, or schemas, rebuild the project, restart the tunnel client, and refresh the plugin from its ChatGPT settings. See the official OpenAI guide for [custom MCP servers](https://developers.openai.com/api/docs/guides/custom-mcp-server) for the current ChatGPT workflow.

> [!IMPORTANT]
> The server uses the Google credentials configured in `.env`. Everyone authorized to use this plugin accesses the same logbook, so associate the tunnel and plugin only with the intended account or workspace.

TDQS

A4.1/5.0

Scored across 4 tools

Disambiguation5/5

The tools are clearly separated by scope: listing files versus reading a month, a year, or the entire logbook. The descriptions explicitly state the boundaries, so an agent can choose the correct read tool without ambiguity.

Naming Consistency5/5

All tool names use snake_case with a predictable verb_noun structure: list_logbook_files and read_logbook_{month,year,entire}. The convention is consistent and readable throughout.

Tool Count5/5

Four tools is well-scoped for a read-only logbook browser. Each tool maps to a distinct level of access, and none feels redundant or missing at this scope.

Completeness4/5

The read-only surface is well covered: listing, monthly, yearly, and full-logbook reads are all present. Minor gaps remain, such as reading a single worksheet directly or deriving summary gym stats, but core access workflows are complete.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues