# Nike Run Club MCP Server

A local [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that gives MCP clients read-only access to your Nike Run Club running history.

The server can list running activities and retrieve detailed metrics such as distance, pace, heart rate, and GPS samples. It was inspired by [niw's research into the NikePlus API](https://gist.github.com/niw/858c1ecaef89858893681e46db63db66).

> [!WARNING]
> This project uses undocumented, non-public Nike APIs. The endpoints may change or stop working without notice. Your bearer token grants access to private account data; treat it like a password and never commit it, paste it into an issue, or share it in chat.

## Requirements

- Node.js 20 or later
- A Nike API bearer token for your own Nike account
- An MCP client such as Codex

## Installation

```bash
git clone https://github.com/tsutsutaku/nike-runclub-mcp.git
cd nike-runclub-mcp
npm install
npm run build
```

Set the bearer token in the environment that launches your MCP client:

```bash
export NIKE_BEARER_TOKEN="YOUR_BEARER_TOKEN"
```

You can obtain your own token by inspecting requests made by the Nike Run Club app to `api.nike.com` and locating the `Authorization: Bearer ...` request header. The exact process depends on the device and app version, so this project does not automate login or token extraction.

## Codex setup

This repository includes a project-scoped [`.codex/config.toml`](.codex/config.toml). After exporting the token, launch Codex from the repository:

```bash
export NIKE_BEARER_TOKEN="YOUR_BEARER_TOKEN"
codex
```

Trust the project when prompted. Codex only loads project-scoped configuration for trusted projects. Use `/mcp` to confirm that `nike-runclub` is connected.

The configuration forwards `NIKE_BEARER_TOKEN` from Codex's parent environment. Merely placing the token in a `.env` file does not load it automatically; export it in your shell or provide it through a secure environment/secret manager.

## Other MCP clients

Use the following as a starting point, replacing the path with the absolute path to your clone:

```json
{
  "mcpServers": {
    "nike-runclub": {
      "command": "node",
      "args": ["/absolute/path/to/nike-runclub-mcp/dist/index.js"],
      "env": {
        "NIKE_BEARER_TOKEN": "YOUR_BEARER_TOKEN"
      }
    }
  }
}
```

Prefer your client's secret-management or environment-forwarding feature over storing the token directly in configuration.

## Tools

### `list_runs`

Lists running activities in reverse chronological order.

| Argument | Type | Default | Description |
| --- | --- | --- | --- |
| `after_time` | integer | `0` | Only return activities at or after this Unix epoch timestamp in milliseconds. Use `0` for all history. |
| `limit` | integer | `100` | Maximum number of activities to return, from 1 to 500. |
| `max_pages` | integer | `10` | Maximum number of Nike API pages to request, from 1 to 100. |

### `get_run`

Retrieves one activity by the ID returned from `list_runs`.

| Argument | Type | Default | Description |
| --- | --- | --- | --- |
| `activity_id` | string | required | Nike activity ID. |
| `include_all_metrics` | boolean | `true` | Request detailed metrics with `metrics=ALL`. |

Example prompts:

- "List my 10 most recent runs."
- "Analyze the pace and heart-rate data for this activity."
- "Summarize my running distance since the beginning of this month."

## Environment variables

| Variable | Required | Default | Description |
| --- | --- | --- | --- |
| `NIKE_BEARER_TOKEN` | yes | — | Bearer token for your Nike account. |
| `NIKE_API_TIMEOUT_MS` | no | `30000` | Nike API request timeout in milliseconds. |
| `NIKE_API_BASE_URL` | no | `https://api.nike.com` | API base URL, primarily useful for testing. |

## Development

```bash
npm run check
```

This command compiles the TypeScript project and runs the test suite. Tests use mocked HTTP responses and do not contact Nike or require a real bearer token.

The activity list currently uses `/plus/v3/activities/before_id/v3/`, while activity details use `/sport/v3/me/activity/`. Both are undocumented Nike endpoints and may change without notice.

## Privacy and security

- The server communicates directly with `api.nike.com`; it does not send your activity data to a separate service.
- The MCP server is read-only and exposes no activity mutation or deletion tools.
- `.env`, build output, and dependencies are excluded from Git.
- Revoke or replace the bearer token if you accidentally expose it.

## Disclaimer

This project is independent and is not affiliated with, endorsed by, or sponsored by Nike. Nike and Nike Run Club are trademarks of Nike, Inc.