NumacoAG/clockify-mcp

clockify-mcp は何をしますか？

Clockify MCPサーバー + Claude Codeプラグイン：Cloud Runでホストされ、OAuth、マルチテナント対応。/log-sessionスキル、プロアクティブな停止フック通知、毎日のカレンダー調整機能を搭載。

概要

このMCPサーバーは、AIエージェント（特にClaude Code）がClockifyの時間追跡機能とシームレスに連携できるようにします。Cloud Run上で動作し、OAuth2.0認証による安全なマルチテナント環境を提供します。

主な機能

• /log-session スキル: 自然言語の指示に基づいて、Clockifyに作業セッションを自動的に記録します。
• プロアクティブな停止フック通知: 長時間実行中のセッションを検出し、ユーザーに停止を促す通知を送信します。
• 毎日のカレンダー調整: ユーザーのカレンダーイベントとClockifyのタイムエントリを照合し、乖離を特定して修正を提案します。

セットアップ

1. 環境変数: 以下の環境変数を設定してください。

   • CLOCKIFY_API_KEY: Clockify APIキー
   • CLOCKIFY_WORKSPACE_ID: デフォルトのワークスペースID
   • OAUTH_CLIENT_ID: OAuthクライアントID（Cloud Run用）
   • OAUTH_CLIENT_SECRET: OAuthクライアントシークレット（Cloud Run用）

2. デプロイ: Cloud Runにデプロイするか、ローカルで実行します。

   # ローカル実行
   python main.py
   

3. Claude Codeとの統合: Claude Codeの設定でこのMCPサーバーを参照するように構成します。

使用方法

• セッションの記録:

  /log-session --project "ProjectX" --description "バグ修正" --duration 2h
  

• セッションの停止:

  現在のセッションを停止してください。
  

• カレンダーの調整:

  今日のカレンダーエントリを確認してください。
  

アーキテクチャ

• バックエンド: Python（FastAPI）
• 展開: Cloud Run（Dockerコンテナ）
• 認証: OAuth2.0
• データベース: セッション状態とユーザーデータの保存にFirestoreを使用（オプション）

貢献

バグ報告や機能リクエストは、GitHub Issuesまでお願いします。

ライセンス

MIT