# three.ws Herald

Spawns a 3D companion inside your browser tab to announce agent task completion or urgent failures out loud. Keeps key alerts noticeable.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 249
- Author: nirholas
- License: Apache-2.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/nirholas/three.ws/tree/HEAD/packages/herald-mcp
- Updated: 2026-10-24
- HTML: https://affpapa.org/en/nevibecode/mcp/threews-herald

## What it does

The server sends priority alerts from your agent directly to your personal channel on `three.ws`. Instead of letting critical updates vanish inside terminal scrollback, an animated avatar steps into your open browser tab, gestures, speaks the message, and provides an optional link. If your hardware lacks a GPU, it falls back to a readable interface card.

It supplies three tools. The `announce` tool handles custom notices with urgency scored from 0 to 100, `announce_result` summarizes finished runs, and `check_rail` tests connectivity quietly. The browser client drops routine spam automatically through importance gates, deduplication, and quiet-hour settings.

If no tab stays open to receive the broadcast, the message expires in five minutes. Running this requires a valid `THREE_WS_API_KEY` scoped to `herald:announce`. Broadcasts target solely the key holder, which prevents accidental notifications to other teammates.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `THREE_WS_API_KEY`, `THREE_WS_BASE`, `THREE_WS_TIMEOUT_MS` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env THREE_WS_API_KEY=<THREE_WS_API_KEY> --env THREE_WS_BASE=<THREE_WS_BASE> --env THREE_WS_TIMEOUT_MS=<THREE_WS_TIMEOUT_MS> --transport stdio herald-mcp -- npx -y @three-ws/herald-mcp
```
Replace <…> with your own values

### Codex

**Platform CLI**
```bash
codex mcp add herald-mcp --env THREE_WS_API_KEY=<THREE_WS_API_KEY> --env THREE_WS_BASE=<THREE_WS_BASE> --env THREE_WS_TIMEOUT_MS=<THREE_WS_TIMEOUT_MS> -- npx -y @three-ws/herald-mcp
```
Replace <…> with your own values

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "herald-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "@three-ws/herald-mcp"
            ],
            "env": {
                "THREE_WS_API_KEY": "<THREE_WS_API_KEY>",
                "THREE_WS_BASE": "<THREE_WS_BASE>",
                "THREE_WS_TIMEOUT_MS": "<THREE_WS_TIMEOUT_MS>"
            }
        }
    }
}
```
Replace <…> with your own values

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "herald-mcp": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "@three-ws/herald-mcp"
            ],
            "env": {
                "THREE_WS_API_KEY": "<THREE_WS_API_KEY>",
                "THREE_WS_BASE": "<THREE_WS_BASE>",
                "THREE_WS_TIMEOUT_MS": "<THREE_WS_TIMEOUT_MS>"
            }
        }
    }
}
```
Replace <…> with your own values

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e THREE_WS_API_KEY=<THREE_WS_API_KEY> -e THREE_WS_BASE=<THREE_WS_BASE> -e THREE_WS_TIMEOUT_MS=<THREE_WS_TIMEOUT_MS> herald-mcp npx -y @three-ws/herald-mcp
```
Replace <…> with your own values

## When to use it
- get spoken alerts whenever prolonged background tasks complete
- catch broken scripts or failing workers without staring at logs
- prompt human intervention when the agent requires quick decisions
- verify notification rail wiring safely with zero-importance tests

## Example prompts
- Run the database migration and notify me through herald when done
- Verify the herald notification pipeline connection
- If the build fails, send a high-urgency herald broadcast with the dashboard link

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 386989
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119160
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47392
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43872

From the same set: [nirholas/three.ws](https://affpapa.org/en/nevibecode/by/nirholas/three.ws.md) — 29 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md