Skip to content
MCP server

Heads-up

Spoken alerts when Claude Code or Codex finishes a task or needs your review

Runs locallyStatus and history
Install
Pricing
Free
Platforms
macOS, Linux, Windows
Runs
Locally
Version
1.7.0
Listing updated
3 days ago

About Heads-up

Heads-up is a free MCP server for developer tools. It runs locally on your machine and is started by your AI client.

Heads-up lets you step away from the keyboard and still know when a coding agent wants you back. The agent calls one tool, notify_user, and the computer plays a short spoken line, such as "Hello from Kosh. I need your review." It ships as a plugin for Claude Code and Codex made of a local MCP server, a skill that teaches the agent when to speak up, and hooks.

Out of the box it plays one of 20 built-in alerts, with 140 clips across 7 voices (American, British, Australian and Indian English), and needs no API key. An optional free local voice model, or your own ElevenLabs or Sarvam key, adds project names, the chat title when several sessions are open, and short messages written by Claude itself, which are cleaned of code and links and capped in length.

It tries to be polite. Alerts stay silent while a microphone or camera is in use or macOS Focus or Do Not Disturb is on, and can be limited to saved networks, quiet hours and an hourly cap. Hooks fire automatically on permission prompts and on turns that run longer than 2 minutes. A stop command or settings-page button cuts an alert off mid-sentence, and volume is briefly raised if the machine is muted, with headphones kept at or below 50%.

Install

Run in a terminal

claude mcp add headsup-mcp -- npx -y headsup-mcp

Add to claude_desktop_config.json

{
  "mcpServers": {
    "headsup-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "headsup-mcp"
      ]
    }
  }
}
Install in CursorOpens Cursor, which asks you to confirm. Or add it by hand:

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "headsup-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "headsup-mcp"
      ]
    }
  }
}
Install in VS CodeOpens VS Code, which asks you to confirm. Or add it by hand:

Add to .vscode/mcp.json

{
  "servers": {
    "headsup-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "headsup-mcp"
      ]
    }
  }
}

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

{
  "mcpServers": {
    "headsup-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "headsup-mcp"
      ]
    }
  }
}

Add to your client's MCP settings (most use this shape)

{
  "mcpServers": {
    "headsup-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "headsup-mcp"
      ]
    }
  }
}

Tools this server provides (1)

Taken from the project documentation; the running server may differ.

notify_user
Plays a short spoken alert, optionally with a message written by the agent.

What it does

One notify tool
The agent calls notify_user to speak a short alert instead of you watching the terminal.
Built-in clips
20 alerts in 7 voices play without any key or account.
Local or paid voices
A free on-device voice, or your own ElevenLabs or Sarvam key, adds project names and Claude's own wording.
Automatic hooks
Permission prompts and turns longer than 2 minutes trigger an alert even if the agent forgets.
Quiet when needed
Silent during calls, Focus or Do Not Disturb, with optional away detection, quiet hours and hourly limits.
Usage visibility
The settings page shows characters used per provider today and this month.
Instant stop
headsup stop or a button on the settings page ends an alert mid-sentence.

Good for

  • Get a spoken cue when a long Claude Code run finishes
  • Hear which of several open sessions needs a permission decision
  • Hear a short status such as a migration result without checking the screen
  • Keep alerts off during calls and focus time
  • Customise what each alert says in your own wording

Pricing

Free

Free; ElevenLabs or Sarvam voices use your own key and plan

Prices change. Check brandbakery.tech before you buy.

Heads-up FAQ

Does it need an API key?

No. The 20 built-in alerts play without one. Project names and Claude's own words need the free local voice or an ElevenLabs or Sarvam key.

Which systems does it run on?

Mac, Linux and Windows, according to the registry entry and README.

Will it interrupt me on calls?

No. It stays silent while a microphone or camera is in use or while Focus or Do Not Disturb is on.

How do I silence an alert already playing?

Run headsup stop, or press Stop on the settings page.

Is Heads-up free?

Yes. Heads-up is free to use.

How do I add Heads-up to Claude Code?

Run this command in your terminal: claude mcp add headsup-mcp -- npx -y headsup-mcp

What are the best alternatives to Heads-up?

The closest alternatives to Heads-up are REA, Codebase Memory, GitHub, Serena MCP: the IDE for your agent and XERJ.

Alternatives to Heads-up

  1. REA

    MCP server

    CLI and MCP server that lets coding agents reverse engineer apps and binaries

    Runs locally
    • Open source
    • 464K GitHub stars
    • Developer tools
  2. Codebase Memory

    MCP server

    Local MCP server that builds a code knowledge graph for AI coding agents

    Runs locally
    • Open source
    • 48.7K GitHub stars
    • Knowledge and memory
  3. GitHub

    MCP server

    Official MCP server connecting AI assistants to GitHub repos, issues and workflows

    Not checked yet
    • Remote
    • Open source
    • 34.5K GitHub stars
    • Developer tools
  4. MCP toolkit giving coding agents symbol-level code retrieval and editing

    Runs locally
    • Open source
    • 31.5K GitHub stars
    • Developer tools
  5. XERJ

    MCP server

    Local search engine for AI agents with cited answers over your code and docs

    Runs locally
    • Open source
    • 19.2K GitHub stars
    • Knowledge and memory
  6. Ha MCP

    MCP server

    MCP server for managing and automating Home Assistant from AI assistants

    Runs locally
    • 8 tools
    • Open source
    • 7.9K GitHub stars
    • Productivity