clockify-mcp-server

Clockifyでプロジェクトの作業時間を記録するには、Web UIをクリックする代わりにエージェントに依頼します。

「今週は毎朝ACMEに4時間、毎午後にEvil Corpに4時間追加して」 → 承認プロンプト1回で、10件のエントリが作成され、合計40時間。

ローカルで動作するstdio MCPサーバーです。各ユーザーが自分のAPIキーで個別に実行します。共有やホスティングは一切ありません。

時刻は常にClockifyプロフィールのタイムゾーンにローカルです。 09:00 と指定すると、サーバーはClockifyプロフィールの settings.timeZone を読み取り、UTCに変換します。UTCを扱う必要はありません。エージェントも同様です。

未対応: タグ、クライアント、実行中タイマー（開始/停止）、既存エントリの編集、レポート。

使う

時間を記録するだけなら、必要なものはすべてここにあります。約2分で完了します。

1. bun と依存関係をインストール（1.3.14で検証済み）:

curl -fsSL https://bun.sh/install | bash # install bun if needed
git clone <this-repo> && cd clockify-mcp-server
bun install

ビルドステップはありません — bunがTypeScriptを直接実行します。

2. Clockify APIキーを取得:

• Clockify → アバター → Preferences → ADVANCED タブ → Manage API keys → GENERATE NEW

3. サーバーをエージェントに登録します。

Claude Code — クローンしたリポジトリのルートから、このままコピーしてください:

claude mcp add clockify -s user -e CLOCKIFY_API_KEY=<key> -- bun "$PWD/src/index.ts"

-s user は個人設定に書き込むため、このリポジトリだけでなくすべてのプロジェクトで読み込まれます（デフォルトのスコープ local はこのリポジトリにバインドされます）。$PWD は claude が参照する前にシェルが展開するため、保存されるパスは絶対パスになります。

他のハーネス（Cursor、VS Code、Zed、Claude Desktop…）も、MCP設定に同じ3つの項目を設定します。貼り付けるパスを出力:

echo "$PWD/src/index.ts"

{
  "mcpServers": {
    "clockify": {
      "command": "bun",
      "args": ["<paste the absolute path here>"],
      "env": { "CLOCKIFY_API_KEY": "<key>" }
    }
  }
}

パスは絶対パスである必要があります: エージェントはこのリポジトリではなく、作業中の任意のディレクトリからサーバーを起動します。

4. 確認 — 新しいセッションで:

list my clockify projects
log 2 hours on <project> today from 09:00 to 11:00, description test
show my clockify entries for this week
delete that entry

2番目のプロンプトの後にClockifyのWeb UIを開き、エントリが 09:00–11:00 と表示されていることを確認してください。異なる時刻が表示されている場合は、Clockifyプロフィールのタイムゾーンが想定と異なっています — Clockifyの設定で修正してください。ここからすべてが連動します。

環境変数

問題が発生した場合

• CLOCKIFY_API_KEY is not set — キーがサーバープロセスに届いていません。ハーネス設定の env に設定してください。シェルではなく。

• Ambiguous project "x". Candidates: … — 意図的な動作です。サーバーはIDを推測しません。リストにある名前のいずれかを使用してください。

• すべての呼び出しで404 — ワークスペースがリージョナルホスト上にあります。CLOCKIFY_API_BASE を設定してください。

• エントリが間違った時刻に記録される — Clockifyプロフィールのタイムゾーンを確認してください（手順4を参照）。

開発

サーバーを使うだけなら、これらは不要です。

bun test      # unit tests, no network
bun run check # biome format + lint, applies fixes
bun run start # start the server on stdio (needs CLOCKIFY_API_KEY)

bun install はgitフック（prepare → lefthook install）もインストールするため、コミット時にステージングされたファイルに対して biome check --write が実行され、修正されたファイルが再ステージされます。その他に設定は不要です。

ローカル実行では、bunはリポジトリルートの .env を自動的に読み込むため、gitignoreされた CLOCKIFY_API_KEY=<key> をそこに置くと、再入力の手間が省けます。これは作業ディレクトリがリポジトリそのものである場合のみ機能します。そのため、上記のハーネス設定ではキーを明示的に渡しています。

レイアウト

src/clockify.ts      # API client, memoised user/project/task lookups, timezone conversion
src/index.ts         # McpServer + the four tools + stdio wiring
src/clockify.test.ts # the parts worth testing: DST conversion, name resolution, payload building
docs/                # Clockify API request/response samples
plans/               # what was built and what was deliberately left out

興味深いコードは src/clockify.ts の localToUtc / interval です — 標準ライブラリの Intl.DateTimeFormat のラウンドトリップで、日付ライブラリは使用していません。変更して bun test を実行してください。DSTのケースがミスを検出します。

bunを持っていない人に配布する場合: bun build --compile --outfile clockify-mcp src/index.ts で、ハーネスが参照する単一の自己完結型バイナリが生成されます。