atimelogger-mcp

ATimeLogger MCP Server

ATimeLogger REST API を AI アシスタントに公開する、スタンドアロンの MCP（Model Context Protocol）サーバーです。stdio 経由でローカルに（Claude Desktop ／ Claude Code ／ OpenAI Codex）、またはコネクターとしてリモートで（ブラウザー版 claude.ai、Claude モバイルアプリ、ChatGPT）利用できます。対象は、アクティビティ（開始／停止／一時停止／記録）、レポート／履歴、アクティビティの種類です。

同じパッケージでは atimelogger-cli もインストールされます。これは AI アシスタントが一切不要な、読み取り専用の JSON CLI です。cron ジョブ、ステータスバー、シェルのパイプラインから利用できます。サーバーと内部機能（あいまいな種類名、期間を表す単語、DST に対応したタイムゾーン処理）を共有しますが、単独で動作します。ライブラリーのエントリーポイントを使えば、独自のコードから ATimeLogger をプロセス内で呼び出すこともできます。

セットアップ

Node 20 以降が必要です。

1. ATimeLogger ウェブアプリでパーソナルアクセストークンを生成します。Settings → API Tokens → Generate token を選択します。値（atl_pat_ で始まります）は一度しか表示されないため、すぐにコピーしてください。トークンはいつでも同じページから失効させられます。

2. サーバーを登録します。インストールやビルドの手順は不要です。初回実行時に npx が公開パッケージを取得します。

Claude Code — 1 行で設定できます。

claude mcp add atimelogger \
  -e ATL_TOKEN=atl_pat_... \
  -- npx -y atimelogger-mcp

Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）または %APPDATA%\Claude\claude_desktop_config.json（Windows）にマージする JSON ブロックです。その後、Claude Desktop を再起動してください。

{
  "mcpServers": {
    "atimelogger": {
      "command": "npx",
      "args": ["-y", "atimelogger-mcp"],
      "env": {
        "ATL_TOKEN": "atl_pat_..."
      }
    }
  }
}

OpenAI Codex（CLI、IDE 拡張機能、または ChatGPT デスクトップアプリの Codex モード）— こちらも 1 行で設定できます。設定は 3 つすべての Codex 環境で共有されます。

codex mcp add atimelogger --env ATL_TOKEN=atl_pat_... -- npx -y atimelogger-mcp

同等の ~/.codex/config.toml ブロック：

[mcp_servers.atimelogger]
command = "npx"
args = ["-y", "atimelogger-mcp"]
env = { "ATL_TOKEN" = "atl_pat_..." }

Codex の MCP サポートにプランの制限はありません。Codex を利用できる ChatGPT サブスクリプション、または通常の API キーがあれば動作します。ChatGPT のウェブ／モバイルアプリからツールを利用する場合は別の方法になります。下記のChatGPT から接続をご覧ください。

ソースから実行する

公開パッケージの代わりに、クローンしてビルドすることもできます。

git clone https://github.com/zaplitny/atimelogger-mcp && cd atimelogger-mcp
npm install
npm run build
npm run setup        # paste the token, verifies it, prints registration snippets pointing at the local build

トラブルシューティング：いずれかのツールで 401 が返される場合、トークンが無効、期限切れ、または失効しています。Settings → API Tokens で新しいトークンを生成し、MCP 設定の ATL_TOKEN を更新してください。

まだトークンがありませんか？サーバーは ATL_TOKEN を設定しなくてもドキュメント専用モードで起動します。app_help ツール（公式アプリのドキュメント）が使えるため、API アクセスを設定する前に ATimeLogger の機能についてアシスタントに尋ねられます。トークンを設定するまでは、時間記録ツールにセットアップ手順が表示されます。

ツール

ツール	用途
get_current_status	経過時間を含む、実行中／一時停止中のアクティビティ
list_activity_types	アクティビティの種類名をグループツリー形式で表示（他のツールで使用する種類名の参照元）
start_activity	種類名で開始。任意で過去の時刻を指定可能（壁時計時刻を指定する at、または started_minutes_ago）
stop_activity	アクティブなアクティビティを停止（1 つだけアクティブな場合は名前の指定は任意）。同じ過去時刻の指定方法に対応
pause_resume_activity	一時停止または再開
log_interval	完了した記録を遡って登録（壁時計時刻、任意でコメント／タグを指定）
update_activity	時刻を変更せず、既存の記録（実行中または過去）のコメント／タグを変更
time_report	期間（today、this_week、last_month、…、または明示的な日付）ごとに集計した種類別統計
list_intervals	日別にグループ化された生の履歴。ページ分割に対応し、期間は最大 100 日
app_help	公式アプリのドキュメント（atimelogger.pro/docs）— 推測する代わりに、アプリの機能（目標、ウィジェット、同期、エクスポートなど）の仕組みをアシスタントが調べます

ツールでは、人が読みやすい種類名を受け付けます（あいまい一致）。正確に対象を指定する場合は内部 ID もツールの出力やパラメーターに含まれますが、ユーザーには表示されません。所要時間は "2h 15m" 形式の文字列で返されます。時刻は timezone パラメーターが指定されていない限り、ユーザーの ATimeLogger のタイムゾーンで表示されます。

使用例

サーバーを登録した後、アシスタントに頼めること：

タイマー

「作業の記録を開始して」 · 「タイマーを停止して」 · 「読書を一時停止して。10分後に戻る」 · 「今、何を記録してる？」

過去の時刻への変更 — 開始や停止を押し忘れた場合：

「開発の記録を開始して。実際には11:30に始めた」 · 「作業を停止して。20分前に終わった」 · 「14:00から会議に出ているので、記録して」

過去のアクティビティの記録

「昨日の21時から23時まで、読書を2時間記録して」 · 「先週の土曜の朝にジムで90分運動した記録を追加して。タグは『legs』」 · 「23:30から7:15まで寝たので、記録して」

既存のエントリーへの注記

「現在のタイマーにメモを追加して：第3四半期レポートを確認中」 · 「今朝の作業セッションに『client-x』のタグを付けて」 · 「昨日の会議のエントリーを更新して。アーキテクチャの同期ミーティングだった」

レポートと履歴

「今週は何に時間を使った？」 · 「6月の作業時間を週ごとに分けて教えて」 · 「今月と先月の睡眠時間を比較して」 · 「今日記録した内容をすべて表示して」 · 「先週、開発に最も時間を使ったのは何曜日？」

アプリの使い方を確認する — 推測ではなく、公式ドキュメントに基づいて回答します：

「目標はどのように機能する？」 · 「同期に昨日のエントリーが反映されないのはなぜ？」 · 「グループとタイプの違いは？」 · 「CSVにエクスポートできる？」 · 「エントリーの時刻を編集するには？」

組み合わせ — アシスタントがツールを自動で連携します：

「実行中のものを停止して、作業を開始して」 · 「前のエントリーの終了時刻から続けて、その時刻から開発を開始して」 · 「昨日の昼食と会議の間の空白を読書で埋めて」

アクティビティ名は、ユーザー独自のタイプ一覧とあいまい一致で照合されるため、「devを開始して」と頼むと「Development」が見つかります。名前が曖昧な場合、アシスタントが確認します。

コマンドラインインターフェース

atimelogger-cli は同じパッケージでインストールされ、単独で動作します。MCP クライアントもアシスタントも必要なく、同じ ATL_TOKEN 以外の API キーも不要です。MCP の利用が現実的でないスクリプトや自動化（cron ジョブ、ステータスバー、シェルパイプライン）向けの 読み取り専用 JSON CLI であり、MCP ツールの基盤となる内部処理を再利用しています。あいまいなタイプ名、期間を表す語句、DST に正しく対応するタイムゾーン、人間にわかりやすい所要時間に対応しています。

export ATL_TOKEN=atl_pat_...
npx -y -p atimelogger-mcp atimelogger-cli status
atimelogger-cli report --period this_week --type work
atimelogger-cli intervals --period yesterday --tag gym --compact | jq .

コマンド：status、types、report、intervals、および doctor。すべてのオプションは atimelogger-cli --help を実行して確認してください。問題が起きたときは、まず doctor を実行してください。トークンの有無と形式、ホストに到達できるか、トークンで引き続き認証できるか、アカウントに記録可能なタイプがあるかを確認し、原因のレイヤーを示すため、推測する必要がありません。問題がある場合は終了コード1で終了し、トークンを出力することはありません。出力は常に JSON 形式です（デフォルトでは整形済み、1行にするには --compact）。安定したキーを使用します。所要時間には人間にわかりやすい文字列と生の seconds の両方が含まれ、ページングは has_more の真偽値で示され、結果が空の場合もキーを省略せず [] を返すため、何も記録されていない日でも jq パイプラインが壊れません。エラーは {"error": "..."} の形式で stderr に出力され、終了コードは1です（--type で解決できないタイプを指定した場合を含む、使用方法の誤りは2）。CLI は記録の開始、停止、編集を行いません。書き込み操作は、人間が介在する MCP サーバー側で行います。cron からのスクリプトによる書き込みは再試行が発生しやすく、タイムラインを破損するおそれがあります。

ライブラリとしての使用（実験的）

このパッケージは、タスク指向のコアもエクスポートするため、長時間実行するプロセスから、リクエストごとにバイナリを起動する代わりに、プロセス内で ATimeLogger を呼び出せます。これは、デーモン、ボット、エディタープラグインなど、MCP トランスポートを使わずに、あいまいな種類名、期間を表す語句、DST に対応したタイムゾーン、人間が読みやすい所要時間といった利便性を利用したい場合に便利です。

import { createClient, clientFromEnv } from "atimelogger-mcp";

const atl = createClient({ token });    // credentials passed explicitly
// …or, for the single-account case, read ATL_TOKEN + ATL_BASE_URL:
// const atl = clientFromEnv();

// reads
const { active } = await atl.status();
const { duration, seconds, by_type } = await atl.report({ period: "this_week", type_names: ["work"] });
const { days, has_more } = await atl.intervals({ period: "yesterday" });

// writes
await atl.start({ type_name: "development", started_minutes_ago: 10 });
await atl.stop();                                   // name optional if one is active
await atl.pauseResume({ action: "pause" });
await atl.log({ type_name: "reading", from: "2026-08-05 21:00", to: "2026-08-05 22:30" });
await atl.update({ activity_id, comment: "architecture sync" });

await atl.api.get("/api/…");                        // escape hatch for anything unwrapped

createClient({ token: process.env.ATL_TOKEN }) を自分で組み立てるより、clientFromEnv() を使ってください。後者は ATL_BASE_URL を無視するため、本番環境を暗黙のうちに対象にしてしまいます。MCP サーバーや CLI とは異なり、トークンが設定されていない場合は、ホストプロセスを終了せずに例外をスローします。

書き込み処理は api に対して自分で組み立てるのではなく、クライアントに含まれています。処理の順序が重要だからです。update は読み取り・変更・書き込みを行います。生の PUT では、ペイロードに含まれないすべてのインターバルがソフト削除され、エントリの記録済み時間が暗黙のうちに消えてしまうためです。（CLI が読み取り専用なのは別の理由によるものです。プログラムではなく、無人で実行されるシェルの再試行に対応するためです。）

結果は完全に型付けされています（CurrentStatus、TimeReport、IntervalsPage、StartedActivity など）。型でオプションとされているフィールドを除き、すべてのフィールドが存在します。days、active、by_type は、キーが欠落するのではなく空の配列になるため、結果が空でも安全に分割代入できます。所要時間は、人間が読みやすい文字列と生の seconds の両方で取得できます。エラーも型付けされています。UsageError（引数が不正、または種類名を解決できない場合）、ApiError（サーバーが失敗を返した場合。.status を保持）、NetworkError（リクエストが届かなかった場合。元のエラーを .cause に保持）です。

各クライアントは、それぞれ独自の HTTP クライアントとキャッシュを持つため、1 つのプロセス内で複数のアカウントを共存させられます。fetch のオーバーライドを使えば、ネットワークに接続せずに、フィクスチャを使ったテストを簡単に実行できます。

const atl = createClient({ token: "test", baseUrl: "https://example.test", fetch: fakeFetch });

app_help はこのインターフェイスには含まれません。アカウントではなく公開ドキュメントサイトの情報を返すため、MCP ツールのままです。

これらのクライアントはプロセス内でのみ動作します。デーモンも、永続化された状態も、呼び出し間で共有されるものもありません。キャッシュを温めておくには、プロセスを実行し続けてください。ライブラリをインポートしても、環境変数が読み込まれることはありません。パッケージが 0.x の間は実験的な機能です。マイナーリリースでシグネチャが変更される可能性があるため、利用する場合はバージョンを固定してください。

リモートサーバー（カスタムコネクター）

上記のローカル stdio セットアップに加えて、サーバーをリモート MCP サーバーとして実行し、Claude のカスタムコネクターとして接続できます。または、ChatGPT の開発者モード（セクション C）から接続できます。ローカル stdio サーバーを利用できないブラウザー版 claude.ai、Claude モバイルアプリ、ChatGPT の Web／モバイルアプリから ATimeLogger のデータにアクセスしたい場合は、この方法を使ってください。

ここでは、稼働中のエンドポイントへの接続だけを行いたい人と、自分でセルフホストしたい人を対象としています。

A. リモートエンドポイントに接続する

稼働中のインスタンスの HTTPS URL（たとえば、セクション B の手順で自分でホストしたもの）がある場合：

1. ブラウザー（デスクトップまたはモバイル）で claude.ai を開きます。1 回限りの「追加」操作は Web UI で行います。追加すると、モバイルアプリにも表示されます。
2. 設定 → コネクター → カスタムコネクターを追加に移動します。
3. 名前（例：ATimeLogger）と、末尾が /mcp のサーバー URL を入力します。

   https://your-host.example.com/mcp
   

4. 追加をクリックします。
5. 任意のチャットで + メニューを開き、コネクターを選択して、コネクターをオンにします。

あとは普段どおり Claude に話しかけてください。「今は何を記録していますか？」「今週はどこに時間を使いましたか？」などです（使用例を参照）。モバイルでも、会話でコネクターを有効にすれば同じように使えます。

Claude がサーバーに接続する方法に関する注意。 カスタムコネクターは、自分のデバイスではなく、Anthropic のクラウドインフラストラクチャから接続します。モバイルアプリや Claude Desktop でも同様です。エンドポイントにはパブリックインターネット経由で到達できる必要があります。localhost 上のサーバー、VPN の背後にあるサーバー、ファイアウォールでブロックされたサーバーは、自分のマシンからアクセスできても接続できません。

B. リモートエンドポイントをセルフホストする

サーバーは stdio を使用するため、HTTPS 経由で公開するには、手前に小さなプロキシを置いて Streamable HTTP 経由で提供し、その後リバースプロキシで TLS を終端します。動作する構成例は次のとおりです。

1. Docker で HTTP プロキシの背後にサーバーを実行します。 ホストに必要なのは Docker だけです。ソースコードのチェックアウトも Node のインストールも不要です。イメージは、公開されている npm パッケージ と mcp-proxy を取得し、stdio サーバーを Streamable HTTP 経由で提供します。

FROM node:22-slim
RUN npm i -g atimelogger-mcp mcp-proxy
EXPOSE 8080
CMD ["mcp-proxy", "--port", "8080", "--", "atimelogger-mcp"]

再現可能なビルドにしたい場合は、バージョンを固定してください（npm i -g [email protected]）。後でアップグレードする際は、--no-cache を指定して再ビルドするか、固定バージョンを更新してコンテナを再作成します。

ビルドして実行する際は、localhost のみにバインドし、トークンを環境変数として渡します。

docker build -t atimelogger-mcp .
docker run -d --name atimelogger-mcp \
  -p 127.0.0.1:9095:8080 \
  --restart unless-stopped \
  -e ATL_TOKEN=atl_pat_your_token_here \
  atimelogger-mcp

ローカルで起動していることを確認します（単独の GET には 400 Bad Request が返されます。これは想定どおりです。エンドポイントがリッスンしていて、不完全なハンドシェイクを拒否していることを意味します）。

curl -i http://127.0.0.1:9095/mcp

2. TLS リバースプロキシを手前に配置します。 HTTPS サーバーブロック内に記述する nginx の location ブロックの例です。ストリーミング関連のディレクティブ（proxy_buffering off、長めの proxy_read_timeout）が重要です。設定しないと接続が停止します。

location /mcp {
    proxy_pass http://127.0.0.1:9095/mcp;
    proxy_http_version 1.1;

    proxy_set_header Host              $host;
    proxy_set_header X-Real-IP         $remote_addr;
    proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;

    # streaming essentials
    proxy_set_header Connection '';
    proxy_buffering  off;
    proxy_cache      off;
    proxy_read_timeout  3600s;
    chunked_transfer_encoding on;
}

sudo nginx -t && sudo systemctl reload nginx

公開エンドポイントは https://your-host.example.com/mcp になりました。セクション A の手順に従って、Custom Connector として追加してください。

3. Claude に接続する前にテストします（任意）。 MCP Inspector を使うと、エンドポイントを個別に確認できます。

npx @modelcontextprotocol/inspector

トランスポートの種類を Streamable HTTP に設定し、URL を入力して、ハンドシェイクが成功し、ツール一覧が表示されることを確認します。

セキュリティ — 公開する前にお読みください。 リモートサーバーは、コンテナに設定された単一の ATL_TOKEN で認証されます。そのため、URL にアクセスできる人は誰でも、あなたとして ATimeLogger アカウントを操作できます。MCP レイヤーにはユーザーごとのログイン機能はありません。セルフホストする場合：

• エンドポイントを非公開にする（URL を公開しない）か、その手前に認証チェックを設けてください（例：必須ヘッダー、または nginx の Basic 認証）。
• コンテナは上記のように 127.0.0.1 のみにバインドし、生の HTTP ポートが直接公開されないようにしてください。公開される入口は nginx のみです。
• トークンはパスワードと同様に扱ってください。公開された場合は、Settings → API Tokens からローテーションしてください。

C. ChatGPT から接続する（Developer Mode）

同じリモートエンドポイントを、ChatGPT のウェブアプリで Developer Mode（有料プラン）を使ってカスタム MCP アプリとして利用できます。設定場所や手順は随時変更されるため、公式ガイドに従ってください：https://developers.openai.com/api/docs/guides/developer-mode。概要は次のとおりです。

1. ChatGPT の設定で Developer mode を有効にします（現在の設定場所はガイドを確認してください）。
2. URL が /mcp で終わるサーバー用に新しいアプリ／コネクターを作成し、認証を None に設定します（ATimeLogger のトークンはサーバー側にあります。上記のセキュリティに関する注意を参照してください）。
3. チャットで有効にして、いつもどおり話しかけます。「今、何を記録していますか？」「昨日の午後9時から11時まで、読書を2時間記録して」のように指示できます。

注意事項：

• ウェブアプリで一度設定すれば、その後は ChatGPT のモバイルアプリでもコネクターを利用できます。
• ChatGPT は OpenAI のインフラストラクチャから接続するため、エンドポイントを公開してアクセス可能にする必要があります。これは Claude のカスタムコネクターと同じ条件です。
• タイマーの開始／停止や記録の追加などの書き込み操作は、デフォルトで実行前に ChatGPT が確認を求めます。
• プラン、地域、機能に関する制限が適用される場合があり、内容は今後変更される可能性があります。現在の状況は公式ドキュメントで確認してください（Developer Mode と、Deep Research 用の search／fetch 専用 ChatGPT コネクターを混同しないでください。このサーバーは操作ツールを公開するため、Developer Mode が適しています）。

制限事項

• start_activityではコメントを添付できません（基盤となる開始エンドポイントが受け取るのは種別と時刻のみです）。後からupdate_activityでコメントを追加するか、コメントやタグを付けて遡って記録するにはlog_intervalを使用してください。
• 編集できるのは既存のエントリーのコメントとタグのみです（update_activity）。インターバルの時刻は変更できず、エントリーも削除できません。操作にはATimeLoggerアプリを使用してください（アシスタントがapp_helpで手順を説明できます）。
• 履歴のリクエストは、バックエンドによって最大100日間に制限されています。