intervals-mcp

Intervals Extra (intervals-mcp)

intervals.icu のランデータと分析に対応する、インタラクティブな MCP Apps を備えたシングルユーザー向けリモート MCP サーバーです。

すべてのテキストツールと MCP App は intervals.icu と直接通信し、 実際のアカウントで検証されています。全カタログについては docs/tools.md をご覧ください。設定は起動時に確認されます。無効な変数があると、その変数名を示すメッセージとともにサーバーが停止し、キーが設定されているかどうかは /health で報告されます。

履歴。 このプロジェクトは strava-mcp として始まり、データソースを intervals.icu に移行しました。現在、サーバー内で Strava と通信する箇所はありません。

セットアップ

1. intervals.icu API キーを取得する

1. intervals.icu にログインします
2. Settings、Developer Settings の順に開きます
3. 個人用 API キーをコピーします

2. 環境を設定する

cp .env.example .env

.env を編集し、値を設定します。

INTERVALS_API_KEY=your_api_key

すべての変数は docs/operations.md に記載されています。

3. 実行する

ローカル開発（Bun が必要です）：

bun install
bun run dev

Docker：

docker compose up -d

ビルド済みイメージを使う場合は、最新リリースの ghcr.io/ljcl/intervals-mcp:latest をプルし、 （MCP registry では io.github.ljcl/intervals-mcp としても公開されています）、ビルドする代わりに compose の image: をそのイメージに指定します。API キーは引き続きご自身で用意する必要があります。:edge は未リリースの main を追跡します。公開イメージには SBOM／来歴のアテステーションが付属しており、検証できます。詳しくは operations.md をご覧ください。

GET /health は intervals.icu API リクエストを消費せずに稼働状態を報告します。 MCP_AUTH_TOKEN が設定されている場合は、設定とレート制限の状態も報告します。レスポンスの形式と監視方法については、operations.md をご覧ください。

任意のクライアントを http://localhost:3000/mcp に接続してください。リポジトリの構成、タスクランナー、テスト、カバレッジのゲート、Storybook のワークフローについては、docs/development.md をご覧ください。 エージェントの規約は AGENTS.md に記載されています。

AI ツールへの接続

ほとんどの AI ツール（Claude Desktop、Claude Code など）から MCP サーバーに接続するには HTTPS URL が必要です。 サーバーはローカルネットワーク上で実行されるため、外部に公開するにはトンネルが必要です。

Tailscale Funnel（推奨）

Tailscale Funnel は設定不要で、ローカルポートを HTTPS 経由でインターネットに公開します。

tailscale funnel --bg 3000
# → https://your-machine.tail1234.ts.net

.env の PUBLIC_URL に、生成された URL を設定します。

Cloudflare Tunnel

cloudflared tunnel --url http://localhost:3000

エンドポイントの保護

トンネルを使うと、URL を知っている人なら誰でも /mcp にアクセスでき、サーバーに設定された intervals.icu API キーを使えます（キー自体が相手に公開されることはありません）。MCP_AUTH_TOKEN に 長くランダムなシークレット（openssl rand -hex 32）を設定すると、すべての /mcp リクエストで Authorization: Bearer <token> が必須になります。各クライアントの設定例では、ヘッダーを追加する場所を示しています。 このシークレットは /health の詳細情報へのアクセス制御にも使われます。 詳しくは operations.md をご覧ください。

API キーと一緒に .env に設定してください。docker-compose.yml が自動的に転送します。

AI Tool (Claude Desktop, Claude Code, etc.)
    │  HTTPS
HTTPS Tunnel (Tailscale / Cloudflare)
    │  HTTP (localhost:3000)
intervals-mcp Server (Docker / Bun)
    │  HTTPS
intervals.icu API

クライアントの設定

このサーバーは、Streamable HTTP トランスポートに対応するすべての MCP クライアントで動作します。以下の各設定例では、https://your-public-url をトンネルの URL（またはローカル開発の場合は http://localhost:3000）に置き換えてください。また、MCP_AUTH_TOKEN を設定した場合に限り、Authorization ヘッダーを含めてください。

Claude Desktop

Claude の設定ファイル（macOS の場合は ~/Library/Application Support/Claude/claude_desktop_config.json）に追加します。

{
  "mcpServers": {
    "intervals-mcp": {
      "type": "url",
      "url": "https://your-public-url/mcp",
      "headers": { "Authorization": "Bearer your-mcp-auth-token" }
    }
  }
}

新しい設定を読み込むため、Claude Desktop を再起動してください。

Claude Code

claude mcp add --transport http intervals-mcp https://your-public-url/mcp \
  --header "Authorization: Bearer your-mcp-auth-token"

Cursor

プロジェクトの .cursor/mcp.json（すべてのプロジェクトに適用する場合は ~/.cursor/mcp.json）に追加します：

{
  "mcpServers": {
    "intervals-mcp": {
      "url": "https://your-public-url/mcp",
      "headers": { "Authorization": "Bearer your-mcp-auth-token" }
    }
  }
}

VS Code

ワークスペースの .vscode/mcp.json に追加します（または、コマンドパレットから MCP: Add Server を実行します）：

{
  "servers": {
    "intervals-mcp": {
      "type": "http",
      "url": "https://your-public-url/mcp",
      "headers": { "Authorization": "Bearer your-mcp-auth-token" }
    }
  }
}

その他のクライアント（汎用 Streamable HTTP）

Streamable HTTP に対応するクライアントであれば、/mcp エンドポイントに直接接続できます。このエンドポイントは 2026-07-28 リビジョンを提供します。クライアントは、io.modelcontextprotocol/* エンベロープキーと Mcp-Method／Mcp-Name ヘッダーを含むステートレスリクエストを送信します（server/discover で機能を通知します）。2025 年当時のクライアント（initialize で接続を開始するもの）もステートレスに提供されます。これは claude.ai が MCP Apps をその方法で読み込むためですが、書き込みツールは利用できません。update-activity には 2026-07-28 対応クライアントが必要です。Accept: application/json, text/event-stream ヘッダーを付けて JSON-RPC メッセージを POST してください。プロトコルの詳細については、docs/architecture.md をご覧ください。

ツール

ツールの全カタログ、プロンプト、権限の動作、リクエスト例は docs/tools.md に記載されています。すべてのテキストツールと各 MCP App のデータハンドラーは、intervals.icu と直接通信します。

ドキュメント

ドキュメント	内容
docs/tools.md	ツールの全カタログ、プロンプト、権限の動作、リクエスト例
docs/operations.md	環境変数、API キー、ヘルスエンドポイント、レート制限、エンドポイントのセキュリティ
docs/architecture.md	サーバーアーキテクチャ：トランスポート、HTTP レイヤー、キャッシュ、エラー分類、分析計算
docs/api-notes.md	intervals.icu API の呼び出し：認証、エンドポイント、フェーズ 1 および 2 で検証済みの動作
docs/mcp-apps.md	MCP App パッケージ：共有シェル、モバイル、テーマ設定、各アプリの詳細
docs/development.md	モノレポの仕組み：Turborepo、カバレッジゲート、Storybook ゲート、Docker ビルド
docs/releasing.md	リリースの自動化：Conventional Commit に準拠した PR タイトル、release-please、公開
docs/project.md	イシュー追跡とプロジェクトボード
docs/Intervals_MCP_Server.md	このサーバーを使用する Claude プロジェクトのプロジェクトナレッジとしてアップロードする機能リファレンス

PR はスカッシュマージされ、PR タイトルが main 上のコミットになります。そのため、Conventional Commit の形式で記述してください（fix: はパッチ、feat: はマイナー、! または BREAKING CHANGE: フッターはメジャー、chore:／docs:／refactor:／ci: はリリースなし）。CI チェックで形式に準拠しないタイトルは拒否されます。詳しくは docs/releasing.md をご覧ください。

トラブルシューティング

サーバーが起動時に終了する： 修正が必要な変数名が、問題のある変数ごとに1行で表示されます。operations.md を参照してください。

AI ツールがサーバーに接続できない — MCP では HTTPS URL が必要です。トンネル（Tailscale Funnel または Cloudflare Tunnel）を使ってローカルサーバーを公開してください。AI ツールへの接続 を参照してください。

API キーのエラー： まず /health を確認してください。api_key_configured で、サーバーにキーが設定されているかどうかがわかります。api_key_configured が true なのに呼び出しが失敗する場合は、キーが間違っているか、取り消されている可能性があります。intervals.icu の Settings、Developer Settings で新しいキーを生成し、INTERVALS_API_KEY を更新してください。operations.md を参照してください。

今日のランが表示されない、または日付が1日ずれている： /health の time_zone と time_zone_source を確認してください。TZ が設定されていない（または UTC に設定されている）場合、サーバーは intervals.icu のタイムゾーンを使用します。タイムゾーンを選ぶには TZ を設定してください。operations.md を参照してください。

「Cloudflare … がチャレンジを返しました」： intervals.icu の前段にある Cloudflare が、リクエストが intervals.icu に到達する前に停止しました。したがって、これは API キーの問題ではありません。数分待ってから再試行してください。operations.md を参照してください。

クライアントが接続できない（401 または未対応のプロトコルバージョン）： 拒否された /mcp リクエストごとに、ステータス、JSON-RPC コード、およびクライアントが送信した場合はその名前を含む mcp_rejected の行がサーバーログに記録されます。401 はベアラートークンがないか、誤っていることを意味します。コード -32022 は、クライアントのエンベロープに記載された MCP リビジョンをサーバーが提供していないことを意味します。operations.md を参照してください。

サーバーは稼働していて、接続可能ですか？ curl https://your-public-url/health を実行してください。このエンドポイントは intervals.icu API にアクセスせずに応答するため、レート制限に達している場合でも動作します。

許可したのに、読み取りツールについてクライアントが再度確認を求める — リリースによってツール名が変更されたか、入力スキーマが変更された可能性があります。許可はツールの識別情報ごとに保存されるため、その場合は許可が無効になります。リリースノートにはその旨が記載されています。それ以外の場合、設定の保持はクライアント側で行われます。コネクターレベルとツールごとの設定の両方を確認してください。docs/tools.md を参照してください。

ライセンス

MIT