ブログに戻る

Cursor のプッシュ通知: エージェント完了時にスマホへ通知

Cursor のプッシュ通知: エージェント完了時にスマホへ通知

Cursor のエージェントは、コーヒーを淹れている間にモジュールをリファクタリングしてくれます。ただ、通常のローカル実行の完了は、コンピューター上の通知音、または設定でオンにしたシステム通知で知らされるだけです。Cursor の iOS アプリは、エージェントがターンを終えたときにプッシュ通知を送れますが、対象はクラウドエージェントと Remote Control で引き継いだセッションのみで、有料プランと iPhone が必要です。Android 対応は予定されています。

ローカルのエージェント実行が終わったときにスマホへプッシュ通知を受け取りたい場合、Cursor で通知を送る方法は 2 つあります。

  • stop フック。 エージェントのループが終わるたびに、完了、中断、エラーのいずれの場合でも Cursor がスクリプトを実行します。確実で、毎回同じ動作をします。
  • MCP ツール。 Pocket Alert MCP サーバーを追加すると、依頼したときにエージェントが自分で書いたメッセージを使ってプッシュ通知を送れるようになります。

このガイドでは両方の設定方法を説明します。どちらも数分で完了します。

必要なもの

  • Cursor 1.7 以降。フックは 1.7 で追加されました。
  • フック用の jq と curl。
  • Pocket Alert のアカウント、API キー、スマホにインストールしたアプリ。無料プランで十分です。

Dock から起動した Cursor は .zshrc を読み込まないため、そこでエクスポートした環境変数は Cursor から見えません。代わりにキーをファイルに保存しておきましょう。

mkdir -p ~/.config/pocketalert
printf '%s' 'YOUR_API_KEY' > ~/.config/pocketalert/key
chmod 600 ~/.config/pocketalert/key

方法 1. 実行ごとの stop フック

スクリプト

Cursor はフックに JSON オブジェクトを標準入力で渡します。stop の場合、status(completed、aborted、error のいずれか)と、ウィンドウで開いているフォルダの workspace_roots が含まれます。次の内容を ~/.cursor/hooks/pocketalert.sh として保存してください。

#!/usr/bin/env bash
payload=$(cat)
project=$(basename "$(jq -r '.workspace_roots[0] // "cursor"' <<<"$payload")")
status=$(jq -r '.status // "completed"' <<<"$payload")

case "$status" in
  completed) title="Cursor finished · $project"; level=default ;;
  error)     title="Cursor hit an error · $project"; level=high ;;
  *)         echo '{}'; exit 0 ;;
esac

jq -n --arg t "$title" --arg m "Agent run $status" --arg l "$level" \
  '{title: $t, message: $m, level: $l}' |
  curl -sS --max-time 5 https://api.pocketalert.app/v1/messages \
    -H "Token: $(cat ~/.config/pocketalert/key)" \
    -H 'Content-Type: application/json' \
    --data-binary @- >/dev/null 2>&1 || true

echo '{}'
chmod +x ~/.cursor/hooks/pocketalert.sh

中断された実行は意図的にスキップしています。停止ボタンを押したのであれば、結果はすでにわかっているためです。スクリプトが {} を出力しているのは、stop フックが followup_message を返せるからです。これは Cursor がエージェントへ次のプロンプトとして送り返すメッセージです。空のオブジェクトは「追加することはない」という意味になります。

Pocket Alert CLI を使う場合

Pocket Alert CLI 2.0 以降をインストールしていれば、curl のブロックは 1 行のコマンドに短くなります。テキストのエスケープは CLI が行い、キーは pocketalert auth から読み込まれます。

pocketalert send -t "$title" -m "Agent run $status" -l "$level" -q >/dev/null 2>&1 || true

位置引数ではなく -t と -m を使ってください。Markdown のリストのように、ダッシュで始まる返答が、そうしないとオプションとして解釈されてしまうためです。

登録する

~/.cursor/hooks.json を作成します。

{
  "version": 1,
  "hooks": {
    "stop": [
      { "command": "/Users/you/.cursor/hooks/pocketalert.sh", "timeout": 10 }
    ]
  }
}

スクリプトには絶対パスを指定してください。/Users/you はご自身のホームディレクトリに置き換えます。ホームフォルダ内のファイルはすべてのプロジェクトに適用されます。特定のプロジェクトだけに適用したい場合は、リポジトリ内の .cursor/hooks.json に置いてください。

Cursor はファイルが変更されると hooks.json を自動で再読み込みします。エージェントに小さなタスクを与えてみてください。終了すると、スマホに Cursor finished · your-project と表示されます。

プッシュ通知にエージェントの回答も含めたい場合

stop にはエージェントの返答は含まれませんが、afterAgentResponse には text として含まれます。ステータスだけでなく回答の冒頭を通知したい場合は、同じ形式のスクリプトを afterAgentResponse に登録し、標準入力から .text を読み取ってください。これは応答のたびに実行されるため、通知が多くなります。多くの人は stop のままにしています。

方法 2. MCP サーバー

フックは実行が終わったことを知らせます。MCP サーバーを使うと、エージェント自身が何が起きたかを伝えられます。~/.cursor/mcp.json に Pocket Alert を追加してください。

{
  "mcpServers": {
    "pocketalert": {
      "url": "https://mcp.pocketalert.app/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

前述の Dock の問題があるため、キーはファイルに直接書き込みます。このファイルはリポジトリではなくホームフォルダにあります。キーを環境変数にエクスポートしたうえでターミナルから Cursor を起動する場合は、代わりに "Bearer ${env:POCKETALERT_API_KEY}" を使えます。

Cursor の設定で MCP のセクションを開き、pocketalert にツールが表示されていることを確認してから、次のように依頼します。

> Run the test suite. When it's done, push me the number of failures with Pocket Alert.

エージェントは、自分で書いた要約とともに create_message を呼び出します。level も指定できるため、テストが失敗した場合は high で届けることができます。有料プランであれば、アクションボタンを付けることもできます。

プロンプトごとに指示するのではなく習慣にしたい場合は、プロジェクトルールを追加してください。

When a task takes more than a few minutes, finish by calling the pocketalert
create_message tool with a one-line summary. Use level "high" if anything failed.

どちらを使うか

stop フックMCP ツール
発火タイミング実行のたびに必ずエージェントが判断したとき
メッセージステータス: completed または errorエージェントが書いた内容
必要なものスクリプトと hooks.jsonmcp.json の 1 ブロック
黙って失敗する可能性ネットワークが切れている場合のみモデルが忘れた場合

両方を組み合わせるのがおすすめです。フックですべての実行を必ず把握でき、MCP ツールで重要な場面の内容を受け取れます。

承認待ち

Cursor には「エージェントが承認を待っている」ことを知らせるフックがありません。beforeShellExecution と preToolUse は、Cursor が確認なしで実行するものも含めて、すべてのコマンドの前に発火します。そのため、あなたの対応が本当に必要な場面はわかりません。現時点では、Cursor 独自のデスクトップ通知と iOS アプリがその役割を担っています。

エージェントに危険な操作の前で停止して確認を求めてほしい場合は、MCP ツールを与え、承認と拒否のアクションボタン付きのプッシュ通知を送るルールを設定してください。Human-in-the-loop 通知では、これを単なるお願いではなく確実なゲートにする方法を紹介しています。

通知が届かない場合

  • スクリプトを手動で実行する: echo '{"status":"completed","workspace_roots":["/tmp/demo"]}' | ~/.cursor/hooks/pocketalert.sh。プッシュ通知が届かない場合は、>/dev/null 2>&1 を削除すると curl のエラーを確認できます。
  • フックが動かない場合は Cursor を再起動する。 通常、hooks.json を変更すると Cursor は自動で再読み込みします。
  • hooks.json のパスが絶対パスになっているか、スクリプトに実行権限があるか確認する。
  • MCP の場合はツール一覧を確認する。 Cursor の MCP 設定でサーバー名の横にエラーが出ている場合、通常はキーが間違っているか空になっています。

FAQ

Cursor にはプッシュ通知が組み込まれていますか?

コンピューター上では組み込まれています。完了時の通知音とシステム通知があります。スマホでは、Cursor の iOS アプリが、クラウドエージェントや Remote Control で引き継いだセッションのターンの完了時に通知します。有料プランと iPhone が必要です。通常のローカル実行はコンピューター上で完結するため、ここで紹介する設定の対象になります。

バックグラウンドエージェントやクラウドエージェントでも使えますか?

~/.cursor/hooks.json のフックはご自身のマシン上でのみ動作するため、ローカルで動くエージェントが対象です。クラウドエージェントは Cursor のサーバー上で動きます。リポジトリの .cursor/hooks.json にあるプロジェクトフックは実行されますが、ユーザーフックは実行されず、キーファイルも存在しません。クラウドエージェントでは、エージェントに MCP サーバーが設定されていれば MCP の方法が使えます。または、Cursor の iOS アプリや Slack 連携を利用してください。

エージェントから私の API キーは見えますか?

フックの方法では見えません。キーはスクリプトだけが読めるファイルに保存されます。MCP の方法では、キーは Cursor の設定に保存され、MCP サーバーへ送信されます。モデルには送られません。

無料で使えますか?

はい。フックと MCP は Cursor の機能の一部で、Pocket Alert の無料プランでは 1 台のデバイスで 1 日 50 件までメッセージを送れます。

API キーを取得してフックを追加し、Cursor の作業が終わったときに知らせてもらいましょう。

この記事をシェア