Toggl MCP Server

Toggl MCP サーバー

MCP クライアントが Toggl Track と連携し、自然言語を通じて時間の記録、プロジェクト管理、ワークスペース操作を行えるようにします。

機能

ツール

プロジェクト管理

• create_project

  • 説明: 指定した Toggl ワークスペースに新しいプロジェクトを作成します。
  • 入力:
    • name (str): 作成するプロジェクトの名前です。必須フィールドです。
    • workspace_name (str, optional): プロジェクトを作成するワークスペースの名前です。指定しない場合は、ユーザーのデフォルトのワークスペースが使用されます。
    • active (bool, optional): プロジェクトがアクティブかどうかを指定します。デフォルトは True です。
    • billable (bool, optional): プロジェクトが請求対象かどうかを指定します。デフォルトは False です。
    • client_id (int, optional): プロジェクトに関連付けられたクライアントの ID です。
    • color (str, optional): プロジェクトに割り当てる 16 進数のカラーコードです（例: "#FF0000"）。
    • is_private (bool, optional): プロジェクトが非公開かどうかを指定します。デフォルトは True です。
    • start_date (str, optional): ISO 8601 形式のプロジェクト開始日です（例: "YYYY-MM-DD"）。
    • end_date (str, optional): ISO 8601 形式のプロジェクト終了日です（例: "YYYY-MM-DD"）。
    • estimated_hours (int, optional): プロジェクトの推定時間数です。
    • template (bool, optional): プロジェクトがテンプレートかどうかを指定します。デフォルトは False です。
    • template_id (int, optional): プロジェクトの作成に使用するテンプレートの ID です。
  • 出力: 新しく作成されたプロジェクトのデータを含む JSON レスポンスです。

• delete_project

  • 説明: 指定したワークスペース内で、名前によって識別されるプロジェクトを削除します。
  • 入力:
    • project_name (str): 削除するプロジェクトの正確な名前です。必須フィールドです。
    • workspace_name (str, optional): プロジェクトが含まれるワークスペースの名前です。指定しない場合は、ユーザーのデフォルトのワークスペースが使用されます。
  • 出力: プロジェクトの削除が成功したことを示す確認メッセージ（str）です。

• update_projects

  • 説明: パッチ操作を使用して、指定したワークスペース内の複数のプロジェクトを一括更新します。
  • 入力:
    • project_names (List[str]): 更新するプロジェクト名のリストです。必須フィールドです。
    • operations (List[dict]): 選択したプロジェクトに適用するパッチ操作のリストです。各操作は、操作の種類（op）、フィールドパス（path）、新しい値（value）を指定する辞書です（例: {"op": "replace", "path": "/active", "value": false}）。必須フィールドです。
    • workspace_name (str, optional): プロジェクトが含まれるワークスペースの名前です。指定しない場合は、ユーザーのデフォルトのワークスペースが使用されます。
  • 出力: 更新されたプロジェクトのデータを含む JSON レスポンスです。

• get_all_projects

  • 説明: 指定したワークスペース内のすべてのプロジェクトのリストを取得します。
  • 入力:
    • workspace_name (str, optional): プロジェクトを取得するワークスペースの名前です。指定しない場合は、ユーザーのデフォルトのワークスペースが使用されます。
  • 出力: 指定したワークスペースで見つかったプロジェクトデータオブジェクトのリストを含む JSON レスポンスです。

時間記録の管理

• new_time_entry

  • 説明：新しい時間記録を作成します。タイマーを開始する場合（start のみが指定されている場合、または start と duration のどちらも指定されていない場合）、または完了した時間記録を記録する場合（start と stop、または start と duration が指定されている場合）に使用できます。
  • 入力：
    • description（str）：時間記録の説明。
    • workspace_name（str, optional）：ワークスペースの名前。デフォルトはユーザーのデフォルトのワークスペースです。
    • project_name（str, optional）：時間記録を関連付けるプロジェクトの名前。
    • tags（List[str], optional）：時間記録に適用するタグ名のリスト。
    • start（str, optional）：ISO 8601 形式での記録の開始時刻（例："2023-10-26T10:00:00Z"）。実行中の記録を作成する場合、現在の時刻がデフォルトになります。
    • stop（str, optional）：ISO 8601 形式での記録の終了時刻。指定すると、完了した記録が作成されます。
    • duration（int, optional）：記録の長さ（秒）。start が指定されているが stop が指定されていない場合、duration によって終了時刻が決まります。start が指定されていない場合、負の値を指定すると実行中のタイマーが開始します。
    • billable（bool, optional）：時間記録を請求対象としてマークするかどうか。デフォルトは False です。
    • created_with（str, optional）：記録の作成に使用するアプリケーションの名前。デフォルトは "MCP" です。
  • 出力：作成された時間記録のデータを含む JSON レスポンス。

• stop_time_entry

  • 説明：現在実行中の時間記録を停止します。
  • 入力：
    • workspace_name（str, optional）：記録が実行されているワークスペースの名前。デフォルトはユーザーのデフォルトのワークスペースです。
  • 出力：停止した時間記録のデータを含む JSON レスポンス。

• delete_time_entry

  • 説明：説明と開始時刻を指定して、特定の時間記録を削除します。
  • 入力：
    • time_entry_description（str）：削除する時間記録の正確な説明。
    • start_time（str）：識別に使用する、ISO 8601 形式での記録の正確な開始時刻。
    • workspace_name（str, optional）：記録が含まれるワークスペースの名前。デフォルトはユーザーのデフォルトのワークスペースです。
  • 出力：削除が成功した場合、成功確認メッセージ（str）。

• get_current_time_entry

  • 説明：現在実行中の時間記録の詳細を取得します。
  • 入力：なし（ユーザーのコンテキストが暗黙的に使用されます）。
  • 出力：現在実行中の時間記録のデータを含む JSON レスポンス。時間記録が実行されていない場合は None。

• update_time_entry

  • 説明：説明と開始時刻で識別される既存の時間記録の属性を更新します。
  • 入力：
    • time_entry_description（str）：更新する時間記録の現在の説明。
    • start_time（str）：識別に使用する、ISO 8601 形式での記録の正確な開始時刻。
    • workspace_name（str, optional）：記録が含まれるワークスペースの名前。デフォルトはユーザーのデフォルトのワークスペースです。
    • new_description（str, optional）：時間記録の新しい説明。
    • project_name（str, optional）：記録に関連付ける新しいプロジェクト名。プロジェクトとの関連付けを解除するには、空の文字列 "" を指定します。
    • tags（List[str], optional）：新しいタグ名のリスト。既存のタグはすべて置き換えられます。すべてのタグを削除するには、空のリスト [] を指定します。
    • new_start（str, optional）：ISO 8601 形式での新しい開始時刻。
    • new_stop（str, optional）：ISO 8601 形式での新しい終了時刻。
    • billable（bool, optional）：新しい請求対象ステータス。
  • 出力：更新された時間記録のデータを含む JSON レスポンス。

• get_time_entries_for_range

  • 説明: 現在の日からのオフセットで定義された、指定した日付範囲内の時間エントリーを取得します。
  • 入力:
    • from_day_offset (int): 今日からの開始日のオフセット（例: 今日の場合は0、昨日の場合は-1、1週間前の場合は-7）。
    • to_day_offset (int): 今日からの終了日のオフセット（例: 今日の場合は0、明日の場合は1）。範囲には開始日と終了日の両方が含まれます。
    • workspace_name (str, optional): エントリーを取得するワークスペースの名前。デフォルトはユーザーのデフォルトのワークスペースです。
  • 出力: 指定した日付範囲内で見つかった時間エントリーのリストを含むJSONレスポンス。

はじめに

前提条件

• Python 3.11+
• Toggl Track アカウント
• 依存関係の管理用にuvがインストールされていること

環境変数

mcp_toggl_server フォルダー内に .env ファイルを作成し、次の内容を記述します。

EMAIL=your_toggl_email
PASSWORD=your_toggl_password

Toggl APIトークンを使用する場合：

EMAIL=xxxx
PASSWORD="api_token"

xxxx は個人用トークンを表します。

インストール

まずuvをインストールします。 - MacOS/Linuxの場合： bash curl -LsSf https://astral.sh/uv/install.sh | sh - Windowsの場合： bash powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

uvコマンドを認識させるため、完了後にターミナルを再起動してください。

次に、リポジトリをクローンしてプロジェクトをセットアップします。

git clone [repository-url]
cd mcp_toggl_server
uv venv
uv pip install --all

開発ツールとの連携

VS Code + GitHub Copilot のセットアップ

1. .vscode/mcp.json でMCPサーバーを設定します。

"servers": {
  "toggl": {
    "type": "stdio",
    "command": "uv",
    "args": [
      "--directory",
      "/ABSOLUTE/PATH/TO/PARENT/FOLDER/mcp_toggl_server",
      "run",
      "toggl_mcp_server.py"],
    "envFile": "${workspaceFolder}/mcp_toggl_server/.env"
  }
}

2. 設定を更新します。

   • /ABSOLUTE/PATH/TO/PARENT/FOLDER/mcp_toggl_server をサーバーの絶対パスに置き換えます。
   • コマンド欄にuv実行ファイルのフルパスを指定する必要がある場合があります。MacOS/Linuxでは which uv、Windowsでは where uv を実行すると確認できます。

3. サーバーを有効にします。

   • サーバー設定 /.vscode/mcp.json にカーソルを合わせ、開始ボタンを探します。
   • 開始をクリックすると、Copilotが利用可能なツールを検出します。
   • Copilotでエージェントモードに切り替えます。

詳しいセットアップ手順については、以下を参照してください。

• VS Code の MCP サーバー
• Copilot エージェントモード

その他のMCPクライアントとの連携

Toggl MCP Serverは、MCP互換のクライアントであればどれでも使用できます。連携手順については、以下を参照してください。

1. Claude Desktopについては、MCP クイックスタートガイドを参照してください。
2. その他のMCPクライアントについては、サーバー設定に関する各クライアントのドキュメントを参照してください。

注：通常、設定では、上記のVS Codeのセットアップと同様に、サーバーのパスと環境変数を指定します。

MCP Inspectorでのテスト

開発モードで実行するには：

EMAIL=your_toggl_email PASSWORD=your_toggl_password mcp dev toggl_mcp_server.py

ライセンス

このMCPサーバーはMITライセンスの下でライセンスされています。