toggl-mcp

toggl-mcp

Claude が Toggl Track の時間記録データにアクセスできるようにする、Model Context Protocol (MCP) サーバーです。

Claude に次のようなことを尋ねられます。

• 「今、何の時間を記録していますか？」
• 「今週、各プロジェクトにどれくらい時間を費やしましたか？」
• 「Blog プロジェクトでドキュメントを書くタイマーを開始して」
• 「タイマーを停止して」
• 「昨日は何に取り組みましたか？」

---

ツール

ツール	内容
get_current_timer	現在実行中の時間エントリーを表示します
get_recent_entries	過去 N 日間（デフォルトは 7 日間）の時間エントリーを表示します
get_projects	すべてのプロジェクトを一覧表示します
get_summary	指定した期間のプロジェクト別合計時間を表示します
start_timer	新しい時間エントリーを開始します
stop_timer	現在のタイマーを停止します
get_profile	Toggl のプロフィールとワークスペースを表示します

---

セットアップ

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

1. https://track.toggl.com/profile にアクセスします
2. 一番下までスクロールします
3. API Token の下にある "Click to reveal" をクリックします
4. トークンをコピーします

2. インストール

npm install -g toggl-mcp

インストール先のパスを確認します。

which toggl-mcp

3. Claude Desktop に追加する

~/Library/Application Support/Claude/claude_desktop_config.json を編集します（macOS）。

{
  "mcpServers": {
    "toggl": {
      "command": "/path/from/which/toggl-mcp",
      "env": {
        "TOGGL_API_TOKEN": "your_token_here"
      }
    }
  }
}

または、ソースから実行する場合：

{
  "mcpServers": {
    "toggl": {
      "command": "node",
      "args": ["/path/to/toggl-mcp/dist/index.js"],
      "env": {
        "TOGGL_API_TOKEN": "your_token_here"
      }
    }
  }
}

Claude Desktop を再起動します。Settings → Developer に緑色の「running」バッジが表示されます。

4. テストする

What am I currently tracking in Toggl?

---

クエリの例

毎日のチェックイン：

What have I tracked today in Toggl?

週次レビュー：

Give me a summary of how I spent my time this week by project

時間の記録を開始：

Start a Toggl timer for "reviewing PRs" on my Engineering project

停止して要約：

Stop my timer and tell me how long I worked

生産性分析：

How much time did I track last week vs the week before?
Which project took the most time?

---

開発

git clone https://github.com/yourusername/toggl-mcp
cd toggl-mcp
npm install
npm run build

# Test locally
TOGGL_API_TOKEN=your_token node dist/index.js

プロジェクト構成

toggl-mcp/
├── src/
│   ├── index.ts   # MCP server + tool definitions
│   └── toggl.ts   # Toggl API v9 client + formatters
├── package.json
├── tsconfig.json
└── README.md

---

レート制限

Toggl の無料プランでは、ワークスペースあたり 1 時間に 30 件のリクエストが許可されています。この MCP サーバーは、通常の使用で制限を十分に下回るよう、可能な場合は呼び出しをまとめて処理します（例：プロジェクトとエントリーの並列取得）。

---

コントリビューション

プルリクエストを歓迎します。拡張案：

• タグ管理
• クライアントの一覧表示
• 詳細レポート（日別内訳）
• 時間エントリーの編集

---

ライセンス

MIT

---

謝辞

MCP TypeScript SDK と Toggl Track API v9 を使用して構築しました。