# Heads-up

> Heads-up is a free MCP server for developer tools. Spoken alerts when Claude Code or Codex finishes a task or needs your review. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Free
- **Platforms:** macOS, Linux, Windows, CLI
- **Website:** https://brandbakery.tech
- **Repository:** https://github.com/abhishek207/headsup-mcp
- **MCP Registry name:** io.github.abhishek207/headsup-mcp
- **Categories:** developer tools, productivity
- **Listing updated:** 2026-11-14

## About

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%.

## Features

- **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

## Install

### Claude Code (Terminal)

```sh
claude mcp add headsup-mcp -- npx -y headsup-mcp
```

### Claude Desktop (claude_desktop_config.json)

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

### Cursor (~/.cursor/mcp.json)

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

### VS Code (.vscode/mcp.json)

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

### Windsurf (~/.codeium/windsurf/mcp_config.json)

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

### Other clients (your client's MCP settings (most use this shape))

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

## Tools

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

## 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

- [REA](https://ai-powered.com/mcp/rea): REA is an open-source MCP server for developer tools.
- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Codebase Memory is an open-source MCP server for knowledge and memory.
- [GitHub](https://ai-powered.com/mcp/github-2): GitHub is an open-source MCP server for developer tools.
- [Serena MCP: the IDE for your agent](https://ai-powered.com/mcp/serena-mcp-the-ide-for-your-agent): Serena MCP: the IDE for your agent is an open-source MCP server for developer tools.
- [XERJ](https://ai-powered.com/mcp/xerj): XERJ is an open-source MCP server for knowledge and memory.
- [Ha MCP](https://ai-powered.com/mcp/ha-mcp): Ha MCP is an open-source MCP server for productivity.
- [Ouroboros](https://ai-powered.com/mcp/ouroboros): Ouroboros is an open-source MCP server for developer tools.
- [Claude Code Ultimate Guide](https://ai-powered.com/mcp/claude-code-ultimate-guide): Claude Code Ultimate Guide is an open-source MCP server for ai models and llm tooling.

---
Source: https://ai-powered.com/mcp/heads-up
