Toggl Track MCP Server

Toggl Track MCP サーバー

Toggl Track の時間追跡と連携する Model Context Protocol（MCP）サーバーです。このサーバーを使うと、Claude やその他の MCP クライアントから Toggl Track アカウントに接続して、プロジェクトや時間エントリーを管理できます。

このサーバーは、サーバーの作成を指示するために私が書いた BUILD_APP.md を除き、100％ Claude Code によって書かれています。 十分なテストは行っていません（正直なところ、コードもほとんど読んでいません！）。そのため、改善の余地は確実にあります。

機能

• プロジェクトの取得：Toggl Track アカウントのすべてのプロジェクトを取得します
• ワークスペースの取得：アカウントに関連付けられたすべてのワークスペースを一覧表示します
• 時間エントリーの取得：日付範囲やプロジェクトで絞り込める、詳細な時間エントリーを取得します
• 時間の概要：プロジェクト別の時間レポートを割合付きで集計します
• 現在のタイマー：現在実行中のタイマーと経過時間を確認します
• タイマーの操作：新しいタイマーを開始し、実行中のタイマーを停止します
• タスク管理：見積もり時間付きでプロジェクトのタスクを作成・取得します
• エントリーの検索：説明文で時間エントリーを検索します
• スマートプロンプト：よくある時間追跡の問い合わせ用に、事前に用意された会話のきっかけを提供します
• セキュアな API トークン認証
• LLM での利用に適した、読みやすく整形された出力

クイックスタート

1. Toggl Track API トークンを取得する

1. Toggl Track のプロフィール設定に移動します
2. 「API Token」セクションから API トークンをコピーします
3. 設定手順で使用するため、このトークンを手元に用意します

2. Docker イメージをビルドする

このリポジトリをクローンし、Docker イメージをビルドします：

git clone [email protected]:vontell/toggl-track-mcp.git
cd toggl-track-mcp
docker build -t toggl-track-mcp .

3. Claude Desktop を設定する

Claude Desktop の設定ファイルにサーバーを追加します：

場所： ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）

{
  "mcpServers": {
    "Toggl Track": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TOGGL_API_TOKEN",
        "toggl-track-mcp"
      ],
      "env": {
        "TOGGL_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

重要： "your_api_token_here" を実際の Toggl Track API トークンに置き換えてください。

4. Claude Desktop を再起動する

設定を更新したら、Claude Desktop を再起動して新しい MCP サーバーを読み込みます。

5. インストールを確認する

再起動後、次のような質問を Claude にできるようになります：

• 「Toggl Track にどのようなプロジェクトがありますか？」
• 「『Code review』のタイマーを開始して」
• 「現在のタイマーの状態は？」

---

開発環境のセットアップ

開発とテストを行う場合：

ローカル開発

仮想環境を作成します：

python -m venv .venv
source .venv/bin/activate  # On Windows: venv\Scripts\activate

依存関係をインストールします：

pip install -r requirements.txt

API トークンを設定します：

export TOGGL_API_TOKEN="your_api_token_here"

MCP Inspector でのテスト

mcp dev server.py

これにより、対話形式でテストできる MCP Inspector が開きます。

利用可能なツール

get_projects

Toggl Track アカウントのすべてのプロジェクトを、次の詳細情報とともに取得します：

• プロジェクト名
• ワークスペース ID
• 関連付けられたクライアント
• 色分け
• プライバシー設定

get_workspaces

Toggl Track アカウントに関連付けられたすべてのワークスペースを、次の情報とともに一覧表示します：

• ワークスペース名
• ワークスペース ID

get_time_entries

オプションの絞り込み条件を指定して、詳細な時間エントリーを取得します：

• start_date：開始日で絞り込みます（YYYY-MM-DD 形式。デフォルトは 7 日前）
• end_date：終了日で絞り込みます（YYYY-MM-DD 形式。デフォルトは今日）
• project_name：特定のプロジェクト名で絞り込みます
• エントリーを日付ごとにグループ化し、説明、所要時間、日ごとの合計を表示します

get_time_summary

プロジェクト別の時間の概要を集計して取得します：

• start_date：概要の開始日（デフォルトは 7 日前）
• end_date：概要の終了日（デフォルトは今日）
• project_name：特定のプロジェクトに絞り込みます（任意）
• プロジェクトごとの合計時間を、割合と総合計とともに表示します

get_current_timer

現在実行中のタイマーを確認します：

• アクティブなプロジェクトと説明を表示します
• 経過時間と開始時刻を表示します
• 実行中のタイマーがない場合は「No timer running」を返します

start_timer

新しいタイマーを開始します：

• description：時間エントリーの説明（必須）
• project_name：タイマーを割り当てるプロジェクト名（任意）
• プライマリワークスペースを自動的に使用します
• タイマーの詳細とともに開始確認を返します

stop_current_timer

現在実行中のタイマーを停止します：

• 実行中のタイマーを停止します
• 最終的な所要時間と時間帯を表示します
• 実行中のタイマーがない場合は「No timer running」を返します

search_time_entries

説明で時間エントリーを検索します：

• query：説明内で検索するテキスト（必須）
• start_date：検索範囲の開始日（省略可。デフォルトは30日前）
• end_date：検索範囲の終了日（省略可。デフォルトは今日）
• 大文字と小文字を区別せずに検索し、合計時間を計算します

get_project_tasks

特定のプロジェクトのすべてのタスクを取得します：

• project_name：タスクを取得するプロジェクト名（必須）
• タスク名、ID、ステータス（アクティブ／非アクティブ）、見積もり時間を表示します
• プロジェクトが見つからない場合は、役立つエラーメッセージを返します

create_project_task

プロジェクトに新しいタスクを作成します：

• project_name：タスクを作成するプロジェクト名（必須）
• task_name：新しいタスク名（必須）
• estimated_hours：タスクの見積もり時間（省略可）
• タスクIDと詳細を含む確認メッセージを返します

get_all_tasks

すべてのプロジェクトにまたがるすべてのタスクを取得します：

• プロジェクトとワークスペースごとにタスクを整理して表示します
• タスク名、ID、ステータス、見積もり時間を表示します
• 見つかったタスクの合計数を返します
• タスクにアクセスできないプロジェクトは、問題なくスキップします

プロンプトの例

サーバーには、よくあるシナリオ向けの組み込みプロンプトが用意されています：

時間の記録と分析

• detailed_time_report：時間エントリーの詳細な内訳を取得します
• time_summary_report：プロジェクトごとの集計済み時間サマリーを取得します
• productivity_analysis：作業パターンと生産性を分析します
• current_status_check：現在のタイマーと今日のアクティビティを確認します
• project_deep_dive：特定のプロジェクトの作業を詳しく分析します
• search_by_description：説明のテキストで時間エントリーを検索します

タイマーの操作

• quick_start_timer：説明と任意のプロジェクトを指定してタイマーを開始します
• stop_and_start_new：現在のタイマーを停止して、新しいタイマーを開始します
• timer_status_and_control：ステータスを確認し、タイマー操作のオプションを取得します
• work_session_timer：休憩のリマインダー付きで、集中作業セッションを開始します

タスク管理

• view_project_tasks：特定のプロジェクトのすべてのタスクを表示します
• create_new_task：任意の時間見積もりを指定して新しいタスクを作成します
• task_planning_session：プロジェクトのタスクを計画し、整理します
• project_task_overview：すべてのプロジェクトにまたがるタスクの概要を取得します
• list_all_tasks：すべてのプロジェクトにまたがるすべてのタスクを詳細付きで一覧表示します

使用例

Claude Desktopにインストールすると、次のように尋ねることができます：

プロジェクトとワークスペースに関する質問

• 「Toggl Trackにはどのようなプロジェクトがありますか？」
• 「Togglのワークスペースを表示して」
• 「時間記録用のプロジェクトをすべて一覧表示して」

時間エントリーの分析

• 「先週の時間エントリーを表示して」
• 「昨日は何に取り組みましたか？」
• 「プロジェクトXの時間サマリーを教えて」
• 「今月は各プロジェクトにどれくらい時間を費やしましたか？」
• 「今週の時間エントリーから「meeting」を検索して」

タイマーの操作

• 「現在のタイマーのステータスは？」
• 「プロジェクトABCで「Code review」のタイマーを開始して」
• 「現在のタイマーを停止して」
• 「「Planning session」のタイマーを開始して」

タスク管理

• 「プロジェクトXYZのすべてのタスクを表示して」
• 「プロジェクトABCに「Database migration」という新しいタスクを作成して」
• 「見積もり時間を4時間としてタスクを作成して」
• 「現在のプロジェクトのタスク計画を手伝って」
• 「すべてのプロジェクトにまたがるタスクを一覧表示して」

API リファレンス

このサーバーは Toggl Track API v9 を使用しています。主に使用するエンドポイントは次のとおりです。

• GET /api/v9/me/projects - ユーザーのプロジェクトを取得
• GET /api/v9/workspaces - ユーザーのワークスペースを取得
• GET /api/v9/me/time_entries - 時間エントリーを取得
• GET /api/v9/me/time_entries/current - 現在実行中のタイマーを取得
• POST /api/v9/workspaces/{id}/time_entries - 新しいタイマーを開始
• PATCH /api/v9/workspaces/{id}/time_entries/{id}/stop - タイマーを停止
• GET /api/v9/workspaces/{id}/projects/{id}/tasks - プロジェクトのタスクを取得
• POST /api/v9/workspaces/{id}/projects/{id}/tasks - 新しいタスクを作成

開発

プロジェクト構成

toggl-track-mcp/
├── server.py              # Main MCP server implementation
├── requirements.txt       # Python dependencies
├── .env.example          # Environment variable template
└── README.md             # This file

新機能の追加

このサーバーに Toggl Track の機能を追加する手順は次のとおりです。

1. TogglClient クラスに新しいメソッドを追加します
2. @mcp.tool() デコレーターを使用した新しい関数を作成します
3. 認証とエラーケースを処理します
4. 新機能について、この README を更新します

認証

このサーバーは Toggl Track の API トークン認証方式を使用します。トークンは環境変数 TOGGL_API_TOKEN で指定してください。

セキュリティに関する注意：API トークンをバージョン管理にコミットしないでください。必ず環境変数または安全な構成管理を使用してください。

エラー処理

このサーバーには、次のケースに対応する包括的なエラー処理が含まれています。

• API トークンの構成がない
• ネットワーク接続の問題
• API 認証の失敗
• 形式が正しくない API レスポンス

レート制限

Toggl Track API にはレート制限があります（約 1 リクエスト／秒）。サーバーはこの制限を遵守し、制限を超えた場合は適切なエラーメッセージを表示します。

貢献

問題の報告や機能強化のリクエストをぜひお寄せください！

ライセンス

このプロジェクトはオープンソースで、標準的な条件のもとで利用できます。