# Cursor 푸시 알림 설정: 에이전트 작업이 끝나면 알림 받기

> Cursor 에이전트가 작업을 끝내거나 실패하거나 알릴 내용이 생기면 휴대폰으로 푸시 알림을 받으세요. 모든 실행에 쓰는 stop 훅과 에이전트가 직접 메시지를 쓰는 Pocket Alert MCP 서버를 함께 설명합니다.

*12.10.2026*

<!-- source: https://pocketalert.app/ko/blog/cursor-push-notifications -->

Cursor의 에이전트는 커피를 내리는 동안 모듈 리팩터링을 끝낼 수 있지만, 일반적인 로컬 실행이 끝났을 때 Cursor가 알려 주는 방법은 컴퓨터 안에서만 동작합니다. 소리나 시스템 알림을 켜 두었을 때만 알 수 있죠. Cursor iOS 앱은 에이전트가 한 턴을 마치면 푸시 알림을 보내지만, 클라우드 에이전트와 Remote Control로 넘긴 세션에만 해당하고 유료 플랜과 iPhone이 필요합니다. 안드로이드는 아직 지원 예정입니다.

로컬 에이전트 실행이 끝났을 때 휴대폰으로 푸시 알림을 받고 싶다면, Cursor에서 두 가지 방법을 쓸 수 있습니다.

- **`stop` 훅.** 에이전트 루프가 끝날 때마다 완료, 중단, 오류 여부와 관계없이 스크립트를 실행합니다. 안정적이고 매번 동일하게 동작합니다.
- **MCP 도구.** Pocket Alert MCP 서버를 추가하면, 요청할 때마다 에이전트가 직접 쓴 메시지로 푸시 알림을 보낼 수 있습니다.

이 가이드에서는 두 방법을 모두 설정합니다. 각각 몇 분이면 끝납니다.

## 준비물

- Cursor 1.7 이상. 훅은 1.7부터 지원됩니다.
- 훅에서 사용할 `jq`와 `curl`.
- Pocket Alert 계정, [API 키](/account/apikeys), 그리고 휴대폰의 [앱](/get-app). 무료 플랜으로도 충분합니다.

Dock에서 Cursor를 실행하면 `.zshrc`를 읽지 않으므로, 거기서 export한 환경 변수는 Cursor에 보이지 않습니다. 대신 키를 파일에 저장하세요.

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

## 방법 1. 모든 실행에 쓰는 stop 훅

### 스크립트

Cursor는 stdin으로 JSON 객체를 훅에 전달합니다. `stop`의 경우 `status`(`completed`, `aborted`, `error` 중 하나)와 창에 열린 폴더인 `workspace_roots`가 포함됩니다. 아래 내용을 `~/.cursor/hooks/pocketalert.sh`로 저장하세요.

```bash
#!/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 '{}'
```

```bash
chmod +x ~/.cursor/hooks/pocketalert.sh
```

중단된 실행은 의도적으로 건너뜁니다. 직접 중지를 누른 것이므로 이미 알고 있기 때문입니다. 스크립트가 `{}`를 출력하는 이유는, `stop` 훅이 `followup_message`를 반환하면 Cursor가 이를 다음 프롬프트로 에이전트에 다시 보내기 때문입니다. 빈 객체는 "추가할 내용 없음"을 뜻합니다.

### Pocket Alert CLI 사용

[Pocket Alert CLI](/tools/cli) 2.0 이상을 설치했다면 curl 블록을 명령어 한 줄로 줄일 수 있습니다. CLI가 텍스트 이스케이프를 직접 처리하고, 키는 `pocketalert auth`에서 가져옵니다.

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

`-t`와 `-m`을 위치 인수 대신 그대로 쓰세요. Markdown 목록처럼 하이픈으로 시작하는 응답은 그렇지 않으면 옵션으로 해석될 수 있습니다.

### 등록하기

`~/.cursor/hooks.json` 파일을 만드세요.

```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`에 등록하고 stdin에서 `.text`를 읽으세요. 모든 응답마다 실행되므로 알림이 많아집니다. 대부분은 `stop`을 그대로 씁니다.

## 방법 2. MCP 서버

훅은 실행이 끝났다는 사실을 알려 주고, MCP 서버는 에이전트가 무슨 일이 있었는지 직접 알려 주게 합니다. `~/.cursor/mcp.json`에 Pocket Alert를 추가하세요.

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

위의 Dock 문제 때문에 키를 파일에 직접 적었습니다. 이 파일은 저장소가 아니라 홈 폴더에 있습니다. 키를 export한 상태로 터미널에서 Cursor를 실행한다면 `"Bearer ${env:POCKETALERT_API_KEY}"`를 대신 쓸 수 있습니다.

Cursor 설정에서 MCP 섹션을 열고 `pocketalert`에 도구가 표시되는지 확인한 뒤 다음과 같이 요청하세요.

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

에이전트는 직접 작성한 요약과 함께 `create_message`를 호출합니다. `level`도 설정할 수 있어서, 실패한 테스트 스위트는 `high`로 보낼 수 있고, 유료 플랜에서는 액션 버튼을 붙일 수도 있습니다.

프롬프트마다 지시하는 대신 습관으로 만들려면 프로젝트 규칙을 추가하세요.

```text
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.
```

## 어떤 방법을 쓸까

<div class="cmp-table-wrap">
<table class="cmp-table">
<thead><tr><th></th><th>Stop 훅</th><th>MCP 도구</th></tr></thead>
<tbody>
<tr><th>실행 시점</th><td>모든 실행, 항상</td><td>에이전트가 판단했을 때</td></tr>
<tr><th>메시지</th><td>상태: completed 또는 error</td><td>에이전트가 작성한 내용</td></tr>
<tr><th>필요한 것</th><td>스크립트와 <code>hooks.json</code></td><td><code>mcp.json</code>의 블록 하나</td></tr>
<tr><th>조용히 실패할 수 있는 경우</th><td>네트워크가 끊겼을 때만</td><td>모델이 잊어버렸을 때</td></tr>
</tbody>
</table>
</div>

두 가지를 함께 쓰는 것이 좋은 기본값입니다. 훅은 모든 실행을 놓치지 않도록 보장하고, MCP 도구는 중요한 순간에 내용을 전달해 줍니다.

## 승인 요청

Cursor에는 "에이전트가 승인을 기다리는 중"을 감지하는 훅이 없습니다. `beforeShellExecution`과 `preToolUse`는 Cursor가 묻지 않고 실행하는 명령을 포함해 모든 명령 전에 실행되므로, 실제로 사용자가 필요한 순간을 알려 줄 수 없습니다. 이 경우에는 현재 Cursor의 데스크톱 알림과 iOS 앱이 대신 역할을 합니다.

위험한 단계 전에 에이전트가 멈추고 확인을 받게 하고 싶다면, MCP 도구를 설정하고 승인과 거절 액션 버튼이 있는 푸시를 보내도록 규칙을 추가하세요. [사람 개입 알림](/blog/human-in-the-loop-notifications)에서는 이것을 단순한 부탁이 아니라 실제 게이트로 만드는 방법을 설명합니다.

## 알림이 오지 않는다면

- **스크립트를 직접 실행해 보세요:** `echo '{"status":"completed","workspace_roots":["/tmp/demo"]}' | ~/.cursor/hooks/pocketalert.sh`. 푸시가 오지 않으면 `>/dev/null 2>&1`을 지워서 curl의 오류 메시지를 확인하세요.
- 훅이 여전히 실행되지 않으면 **Cursor를 다시 시작하세요.** 보통은 파일이 바뀌면 `hooks.json`을 자동으로 다시 불러옵니다.
- `hooks.json`의 **경로가 절대 경로인지**, 스크립트에 **실행 권한이 있는지** 확인하세요.
- MCP라면 **도구 목록을 확인하세요.** Cursor MCP 설정에서 서버 옆에 오류가 보이면 보통 키가 잘못되었거나 비어 있다는 뜻입니다.

## 자주 묻는 질문

### Cursor에 푸시 알림 기능이 기본으로 있나요?

컴퓨터에서는 있습니다. 완료 소리와 시스템 알림이 그것입니다. 휴대폰에서는 Cursor iOS 앱이 클라우드 에이전트나 Remote Control로 넘긴 세션의 한 턴이 끝나면 푸시를 보냅니다. 유료 플랜과 iPhone이 필요합니다. 일반적인 로컬 실행은 컴퓨터에 머물며, 이 가이드의 설정이 다루는 부분이 바로 그것입니다.

### 백그라운드 에이전트나 클라우드 에이전트에도 되나요?

`~/.cursor/hooks.json`의 훅은 본인 컴퓨터에서만 실행되므로 로컬에서 도는 에이전트에만 적용됩니다. 클라우드 에이전트는 Cursor 서버에서 실행됩니다. 이 경우 저장소의 `.cursor/hooks.json` 같은 프로젝트 훅은 실행되지만 사용자 훅은 실행되지 않으며, 키 파일도 없습니다. 클라우드 에이전트에는 에이전트에 서버가 설정되어 있다면 MCP 방식이 작동하고, 그렇지 않다면 Cursor iOS 앱이나 Slack 연동을 쓰세요.

### 에이전트가 제 API 키를 볼 수 있나요?

훅 설정에서는 볼 수 없습니다. 키는 스크립트만 읽을 수 있는 파일에 있기 때문입니다. MCP 설정에서는 키가 Cursor 설정에 들어 있고, 모델이 아니라 MCP 서버로 전송됩니다.

### 무료인가요?

네. 훅과 MCP는 Cursor의 기능이며, Pocket Alert 무료 플랜으로 기기 한 대에 하루 50개의 메시지를 보낼 수 있습니다.

[API 키 받기](/signup)를 하고 훅을 추가한 뒤, Cursor가 작업을 끝냈을 때 알려 주도록 설정해 보세요.
