three.ws Herald MCP Server

by nirholasio.github.nirholas/herald-mcpv0.1.0

Tell your human in person: a 3D character walks onto their open browser tab and says it out loud.

228Node.jsstdioofficial registry

context tax

queued

security

queued

cold start

queued

freshness

Active2d ago

Install three.ws Herald MCP server

claude mcp add herald-nirholas -e THREE_WS_API_KEY='<three-ws-api-key>' -- npx -y @three-ws/herald-mcp

{
  "mcpServers": {
    "herald-nirholas": {
      "command": "npx",
      "args": [
        "-y",
        "@three-ws/herald-mcp"
      ],
      "env": {
        "THREE_WS_API_KEY": "<three-ws-api-key>"
      }
    }
  }
}

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project).

{
  "mcpServers": {
    "herald-nirholas": {
      "command": "npx",
      "args": [
        "-y",
        "@three-ws/herald-mcp"
      ],
      "env": {
        "THREE_WS_API_KEY": "<three-ws-api-key>"
      }
    }
  }
}

Settings → Developer → Edit Config (claude_desktop_config.json), then restart.

{
  "servers": {
    "herald-nirholas": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@three-ws/herald-mcp"
      ],
      "env": {
        "THREE_WS_API_KEY": "<three-ws-api-key>"
      }
    }
  }
}

Add to .vscode/mcp.json in your workspace.

{
  "mcpServers": {
    "herald-nirholas": {
      "command": "npx",
      "args": [
        "-y",
        "@three-ws/herald-mcp"
      ],
      "env": {
        "THREE_WS_API_KEY": "<three-ws-api-key>"
      }
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json.

Configuration

Variable	Required	Secret	Description
THREE_WS_API_KEY	yes	yes	A three.ws API key (sk_live_… / sk_test_…) with the herald:announce scope, or an OAuth access token for the same account, carried as Authorization: Bearer. Required: an announcement is always delivered to the key owner's own sessions. Aliases: THREE_WS_TOKEN, THREE_WS_BEARER. Treat like a password.
THREE_WS_BASE	—	—	Base URL of the three.ws API. Override only when self-hosting or targeting a preview deployment.
THREE_WS_TIMEOUT_MS	—	—	Per-request timeout in milliseconds for the announce call.

Freshness

Active — last maintenance signal 2d ago. The newest of the signals below sets the band.

Last commit (default branch)
2026-10-08 · 2d ago · GitHub
Latest release
2026-09-30 · 10d ago · GitHub · v1.5.2
Package published
no data · npm/PyPI
Registry entry updated
2026-09-30 · 10d ago · official registry · v0.1.0

FAQ

›How do I install the three.ws Herald MCP server in Claude Code?

Run: claude mcp add herald-nirholas -e THREE_WS_API_KEY='<three-ws-api-key>' -- npx -y @three-ws/herald-mcp. For Cursor, VS Code, Claude Desktop and Windsurf, use the install tabs above.

›Does three.ws Herald require an API key?

Yes. It expects THREE_WS_API_KEY, of which 1 is a secret.

›Can I use three.ws Herald as a remote (hosted) MCP server?

No hosted endpoint is published; it runs locally over stdio.

›Is three.ws Herald in the official MCP registry?

Yes, as io.github.nirholas/herald-mcp.