Clockify Time Tracking

clockify-mcp

Clockify の 時間追跡 API に対応する Model Context Protocol サーバーです。

AI アシスタントから Clockify のデータにアクセスできます。ワークスペース、プロジェクト、時間記録を照会し、レポートを生成したり、作業時間を記録したり、クライアントや請求書などを管理したりできます。すべて自然言語で操作できます。

18 のドメインにまたがる 112 個のツールを備えています。デフォルトでは読み取り専用で、書き込み操作は明示的に有効にした場合のみ利用できます。

ワンクリックでインストール

Claude Desktop（およびその他の MCPB 対応クライアント）でこのサーバーを使う最も簡単な方法は、ビルド済みバンドルを利用することです。

➡️ clockify-mcp.mcpb をダウンロード — ダウンロードしたファイルをダブルクリックしてください。Claude Desktop がインストーラーを開き、Clockify API キーの入力を求めます。これで完了です。Python も、npx／uvx も、設定ファイルも必要ありません。

.mcpb はすべての GitHub Release に添付され、Smithery にもミラーされています。パッケージマネージャーやコンテナーを使いたい場合は、以下のクイックスタートをご覧ください。

どのようなことができますか？

現在、48 個の読み取り専用ツールを利用できます（フェーズ 0～8b、18 のドメイン）。64 個の書き込みツール（クライアント、プロジェクト、タスク、タグ、時間記録、休日、経費、経費カテゴリの作成／更新／削除に加え、休暇ポリシー／申請の管理、承認の送信／再送信／更新、カスタムフィールドの作成／更新／削除とプロジェクトへの割り当て、スケジュール割り当ての管理、請求書と支払いの管理、共有レポートの管理、Webhook の作成／更新／削除／トークン）は、CLOCKIFY_ACCESS_MODE=full（または後方互換性のある CLOCKIFY_ENABLE_WRITES=true）を設定すると登録されます。中間の time-tracking モードでは、作業時間を記録するための時間記録関連の書き込みツールのみが公開されます。詳しくはアクセスモードをご覧ください。

† 休暇、休日、経費、承認、カスタムフィールド、スケジュール管理、請求書、ウェブフックは Clockify の有料機能です。これらの機能がないプランでは、これらのツールはエラー（HTTP 402/403/404）を返します。 ‡ generate_attendance_report と generate_expense_report（およびこれら 2 種類の export_report）には、ワークスペースの勤怠／経費アドオンが必要です。時間ベースのレポート（詳細／概要／週次）と共有レポートは無料プランで利用できます。

書き込みツール（オプトイン — CLOCKIFY_ACCESS_MODE=full を設定）：

create_expenseとupdate_expenseでは、任意でローカルの領収書ファイルを指定できます。ファイルはmultipartでアップロードされます。

クイックスタート

1. インストール

pip install clockify-mcp

または、インストールせずに実行します（uvが必要です）。

uvx clockify-mcp

または、コンテナイメージを使用します（リリースごとにGHCRに公開されます）。

docker run --rm -i -e CLOCKIFY_API_KEY=your-key ghcr.io/tracegazer/clockify-mcp:latest

2. Claude Desktopに接続

claude_desktop_config.jsonに以下を追加します。

{
  "mcpServers": {
    "clockify": {
      "command": "uvx",
      "args": ["clockify-mcp"],
      "env": {
        "CLOCKIFY_API_KEY": "your-api-key"
      }
    }
  }
}

Claude Desktopを再起動します。「Clockifyにはどのワークスペースがありますか？」と尋ねてみましょう。

{
  "mcpServers": {
    "clockify": {
      "command": "clockify-mcp",
      "env": {
        "CLOCKIFY_API_KEY": "your-api-key"
      }
    }
  }
}

{
  "mcpServers": {
    "clockify": {
      "command": "uvx",
      "args": ["clockify-mcp"],
      "env": {
        "CLOCKIFY_API_KEY": "your-api-key",
        "CLOCKIFY_ACCESS_MODE": "full"
      }
    }
  }
}

3. APIキーを取得

Clockifyにログインし、Profile Settings → APIに移動して、APIキーをコピーします。

設定

設定は次の優先順位で適用されます（上が最優先）。

1. 環境変数（常に優先）
2. ~/.config/clockify-mcp/config.tomlのTOML設定

アクセスモード： readでは読み取りツールのみが公開されます。time-trackingでは、時間を記録するための時間エントリ書き込みツール（create/update/delete/duplicate/bulk）が追加され、それ以外は追加されません。duplicate／bulkは常に認証済みユーザーに対して実行されます。また、IDによるupdate／deleteでは、他のユーザーに属する可能性があるエントリを操作する前に確認するよう、アシスタントに指示されます。fullではすべての書き込みツールが公開されます。この設定で制御されるのはサーバーが登録するMCPツールであり、APIキー自体の権限を置き換えるものではありません。

コピーして使えるテンプレートについては、config.toml.exampleを参照してください。

# ~/.config/clockify-mcp/config.toml
api_key = "your-clockify-api-key"
# region = "global"
# default_workspace_id = ""
# access_mode = "read"   # read | time-tracking | full

ヒント： 先に設定ディレクトリを作成してください：mkdir -p ~/.config/clockify-mcp

サーバーの実行

clockify-mcp                       # STDIO transport (default)
clockify-mcp --transport sse       # SSE/HTTP transport

セキュリティに関する注意： デフォルトのSTDIOでは、すべての処理がローカルで行われます。sseおよびstreamable-httpトランスポートには認証機能が組み込まれていないため、ループバックにバインドするか、認証済みのリバースプロキシの背後でのみ使用してください。

注意事項

• ワークスペースの範囲： Clockify のほぼすべての操作は、ワークスペース（/workspaces/{workspaceId}/...）を対象とします。ツールでは省略可能な workspace_id を指定できます。省略した場合は CLOCKIFY_DEFAULT_WORKSPACE_ID が使用されます。どちらも設定されていない場合、ツールはまず list_workspaces でワークスペースを特定するよう求めます。
• ページネーション： リスト取得ツールは省略可能な page／page_size を受け取り、1 ページ分を返します。大量データを扱うリスト（list_time_entries、list_projects、list_clients、list_tasks、list_tags、list_users）では fetch_all=true も指定できます。ページネーションをたどり、すべてのページを連結して返します（複数回 API を呼び出す場合があります）。
• エラー： 失敗にはカテゴリ（PLAN_REQUIRED、ACCESS_DENIED、AUTH）が付与されるため、アシスタントはプランのアップグレード、モジュールの有効化、キーの修正のいずれが必要か判断できます。Clockify での有料機能と有効化方法をご覧ください。

Clockify での有料機能と有効化方法

多くの機能領域は、互いに独立した 2 つの条件によって制限されており、ツールを動作させるには両方を満たす必要があります。

1. ワークスペースのプランに機能が含まれている必要があります。 含まれていない場合、API は 402（または「subscription」メッセージ）を返し、サーバーはカテゴリ PLAN_REQUIRED の ClockifyAPIError を発生させます。

2. ワークスペースでモジュールを有効にする必要があります。 適切なプランであっても、管理者が Clockify → Workspace Settings で次の項目を有効にする必要があります：Time off、Expenses、Approval、Invoicing、Scheduling。有効になるまでは、API は 403 "Access Denied" を返し、サーバーはカテゴリ ACCESS_DENIED の ClockifyAPIError を発生させます。（カスタムフィールド、Webhook、レポートには個別の切り替え設定は不要です。）

操作に失敗した場合は、エラーカテゴリに対処方法が示されます。

• PLAN_REQUIRED — ワークスペースのプランをアップグレードします（Standard／Pro）。
• ACCESS_DENIED — Workspace Settings で機能を有効にするか、API キーユーザーのロール／権限を確認します。
• AUTH — API キーがない、無効、または取り消されています。

オブザーバビリティ（任意）

サーバーは OpenTelemetry のトレース、メトリクス、ログを出力できます。利用は完全に任意で、ベンダーにも依存しません。OTLP 互換のバックエンド（Dynatrace、Grafana、Datadog、Jaeger など）にエクスポートできます。無効の場合、opentelemetry がインポートされることはありません。

pip install "clockify-mcp[telemetry]"

export CLOCKIFY_TELEMETRY=1

OTLP エンドポイントとヘッダーは、標準の OpenTelemetry 環境変数で設定します（TOML ファイルでは設定しません）。CLOCKIFY_TELEMETRY_DETAIL は、付加する引数／ペイロードデータの量を制御します（既定値は metadata → ids → full）。API キーは常に秘匿されます。

export OTEL_EXPORTER_OTLP_ENDPOINT="https://<your-env>.live.dynatrace.com/api/v2/otlp"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Api-Token <YOUR_DT_TOKEN>"
export OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=delta
export OTEL_SERVICE_NAME=clockify-mcp

export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318"
export OTEL_SERVICE_NAME=clockify-mcp

出力されるシグナル：

• トレース — MCP ツール呼び出し（execute_tool <name>）ごと、および Clockify API リクエストごとのスパン
• メトリクス — mcp.tool.duration、mcp.tool.errors、および Clockify クライアントのリクエスト所要時間
• ログ — ツールエラーと予期しない API レスポンス形式。トレースと関連付けられます（OTLP のみ。標準出力には出力されません）

開発

git clone https://github.com/tracegazer/clockify-mcp
cd clockify-mcp
uv sync --extra dev

CLOCKIFY_API_KEY=dummy uv run clockify-mcp --help
uv run pytest -q
uv run ruff check src/ tests/

ライセンス

MIT