How do I use notch-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@notch-mcp Show a build progressing in the notch, then mark it done." That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

notch-mcp

by avoguru

Overview Schema Source Related Servers Discussions Admin

Local

Notch MCP

A status readout at the top of your Mac that any agent can write to, from any MCP client: Claude Code, Cursor, Windsurf, Zed, Conductor.

Pendant style

Why

Three agents running. One is refactoring, one is partway through the test suite, one has been "almost done" for ten minutes, and you can't tell which without finding the right window and reading back through scrollback.

So you check less often. Then you forget, and something that finished four minutes ago sits there waiting for you.

The expensive part was never the two seconds of switching. It's that after you switch, you don't come back.

Being an MCP server rather than an editor extension is what makes the fix portable. Any agent in any MCP client calls one tool, and you get a line at the top of your screen you can read without leaving what you're doing.

Related MCP server: mcp-notifications

Install

git clone https://github.com/avoguru/notch-mcp.git
cd notch-mcp
npm install

Then add it to your agent.

Claude Code

claude mcp add notch --scope user -- node "$(pwd)/bin/server.mjs"

Cursor, in ~/.cursor/mcp.json

{
  "mcpServers": {
    "notch": {
      "command": "node",
      "args": ["/path/to/notch-mcp/bin/server.mjs"]
    }
  }
}

Conductor runs Claude Code underneath, so the Claude Code command covers it. Use --scope user so every workspace gets it.

Windsurf, in ~/.codeium/windsurf/mcp_config.json, same shape as Cursor.

Zed, in context_servers in settings.json, same shape as Cursor.

Try it

Ask your agent:

Show a build progressing in the notch, then mark it done.

Styles

Four readouts for four kinds of job. Your agent calls notch_styles and picks one on its own. Default is pendant.

pendant, for the thing you're waiting on

pendant

Hangs below the notch, sized to its text. The bottom edge fills as it progresses. For builds, test runs, deploys.

belt, for background work you can ignore

belt

A thin strip across the whole display. Label on the left, detail and percent on the right (both ends shown above). The whole strip fills as it progresses. For syncs, watchers, queues.

pill, for a quick message

pill

A capsule floating below the notch. No progress bar. For "deployed", "pushed", "done in 12s".

glow, for when something is happening

glow

A line of light under the notch and nothing else. No text. The bright segment travels as it progresses. For when you only need to know it's alive.

Tools

Tool	What it does
`notch_styles`	Lists the styles so the agent can choose
`notch_status`	Show or update, with `text`, `detail`, `progress`, `style`
`notch_done`	Green, then hides itself
`notch_error`	Red, stays a bit longer
`notch_clear`	Hide now

A typical run:

notch_status  { text: "Running test suite", progress: 0,    style: "pendant" }
notch_status  { text: "Running test suite", progress: 0.68, detail: "342/500" }
notch_done    { text: "Tests passed",       detail: "500 in 41s" }

Getting rid of it

Click it. On pendant, pill and glow you can click anywhere on the readout; the belt has an × on the right because it spans the screen.

It also clears itself:

when your agent finishes
when you quit or force-quit your editor
after 30 minutes if something was left running

It can't get stuck on screen, and there's nothing to clean up by hand.

Supported

macOS · Node 18+ · zero runtime dependencies

Needs Xcode Command Line Tools for the display component (xcode-select --install). npm install builds it.

Tested on MacBook Pro 16" (M4 Pro), macOS 15.6 Sequoia.

Works with the lid closed or on an external monitor. There's no notch to hang from, so the readouts sit under the menu bar instead.

Contributions welcome

Plenty left to do. A few I'd find useful:

Stack concurrent agents. One readout shows at a time and the most recently updated session wins. Three agents visible in the belt at once would be better, and it's the thing this most needs.
More styles. docs/catalogue.html has 33 treatments that were explored. Four shipped.
Windows and Linux. The MCP server is portable. The renderer is AppKit.
A rules snippet so agents call it consistently without being asked each time.

bin/server.mjs is about 300 lines with no dependencies, so it's readable end to end if you want to see what an MCP server is underneath. Open an issue or a PR.

Development

npm test             # 28 checks against the real server and display
npm run shots        # re-render docs/img at 3x (npm run shots 4 for 4x)
npm run build        # rebuild bin/notchd

License

MIT

Available Tools

5 tools

notch_clearA

Hide the readout immediately.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A3.7/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It adds only the word 'immediately' which hints at instant execution, but it does not mention side effects, reversibility, or any state changes beyond hiding the readout. This is minimal disclosure for a tool that could have subtle effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, succinct sentence that is front-loaded and free of any filler. It is appropriately sized for a tool with no parameters and no annotations.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complete absence of parameters, output schema, and annotations, the description provides all the essential information needed to invoke the tool correctly. The simple action of hiding the readout is fully captured by the one-sentence description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, and the schema is empty. The baseline for 0 parameters is 4, and since there are no parameters to describe, the description appropriately adds nothing in this regard.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly specifies the action ('Hide') and the resource ('the readout'), conveying the tool's purpose directly. It distinguishes itself from siblings like notch_styles and notch_status by describing a distinct hiding/clearing behavior.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description offers no guidance on when to use this tool versus alternatives. There are no references to prerequisites, exclusions, or other sibling tools, leaving the agent without context for selecting this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

notch_doneA

Resolve the current task: flash green, then auto-hide. Use for "complete" updates at the end of long work.

ParametersJSON Schema

Name	Required	Description
`text`	No	Completion label. Defaults to "Complete".
`detail`	No	Optional figure, e.g. "500 passed in 41s".
`dismissAfter`	No	Seconds to linger before hiding. Default 6.

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states the visual outcome (flash green, auto-hide) and the semantic context (resolve current task). While it doesn't detail side effects or edge cases, the disclosed behavior is sufficient for a simple notification tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two tightly written sentences, front-loaded with the core action ('Resolve the current task: flash green, then auto-hide') followed by a concise usage note. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with no output schema and a fully described schema, the description provides the necessary context: what the tool does, when to use it, and what the user sees. It doesn't elaborate on interactions with siblings or edge cases, but given the low complexity, this is sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema descriptions cover 100% of parameters, each with clear meanings (completion label, optional detail, dismissal delay). The tool description adds no extra parameter-level semantics, so the baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb 'Resolve' and identifies the resource 'current task,' with clear behavior 'flash green, then auto-hide.' It distinguishes itself from siblings like notch_error and notch_status by explicitly targeting 'complete' updates at the end of long work.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly states when to use: 'Use for "complete" updates at the end of long work,' giving clear context. It does not mention alternatives or exclusions, but the usage context is specific enough given the sibling tool names.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

notch_errorA

Resolve the current task as failed: flash red and linger longer than a success.

ParametersJSON Schema

Name	Required	Description
`text`	No	Failure label, e.g. "Build failed".
`detail`	No	Optional figure, e.g. "3 errors".
`dismissAfter`	No	Seconds before hiding. Default 12.

TDQS

A3.7/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It discloses visual behavior (flash red, longer duration than success) and implies auto-dismissal, but it does not state potential side effects like clearing existing notifications or how it interacts with other statuses.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence, front-loaded with the action and outcome. It contains no redundant words and effectively conveys the tool's essence.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple notification tool with full schema coverage and no output schema, the description is adequate but not rich. It covers purpose and key visual behavior, but lacks explicit usage guidance, default value explanations (though schema has them), or edge-case handling.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds no parameter-specific meaning beyond the schema; it does not mention text, detail, or dismissAfter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: to resolve the current task as failed, with specific visual behavior (flash red, linger longer than success). This distinguishes it from sibling tools like notch_done (likely success) and notch_clear.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'Resolve the current task as failed' implies usage for error/failure scenarios, and the contrast with 'success' hints at alternatives, but there is no explicit when-to-use, when-not-to-use, or named alternative tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

notch_statusA

Show or update a status readout in the notch. Call when starting long-running work and again as it progresses. Does not steal focus and needs no window. Always finish with notch_done or notch_error so the readout resolves instead of just vanishing.

ParametersJSON Schema

Name	Required	Description
`ttl`	No	Seconds before this status self-expires if never updated. Default 1800.
`text`	Yes	Short label, e.g. "Running test suite". Under ~40 chars.
`style`	No	Which readout to use. 'pendant' (high attention): The one task the user is actively waiting on: a build, a test suite, a deploy, a long agent run. 'belt' (medium attention): Ambient background work the user should be able to ignore: a watcher, a sync, a queue draining, polling. 'pill' (medium attention): A short transient message with no percentage: "Deployed to staging", "Branch pushed", "3 files changed". 'glow' (low attention): Signalling only that something is happening, when the detail does not matter: background indexing, a warm-up, a keepalive. Defaults to pendant.
`detail`	No	Optional secondary figure, e.g. "342/500" or "12.4 MB/s".
`progress`	No	Completion 0–1. Omit for indeterminate, which animates a sweep.

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the transparency burden. It adds valuable behavioral context: 'Does not steal focus and needs no window' and explains that readouts must be resolved via notch_done or notch_error instead of vanishing. This goes beyond the schema, though it does not mention TTL expiry behavior (which the schema's ttl param already covers).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is only two sentences long, front-loaded with the core purpose, and every sentence earns its place. It includes usage guidance and behavioral caveats without any fluff or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

This is a simple tool with 5 fully described parameters and no output schema. The description supplies crucial usage context (when to call, how to resolve the readout) and behavioral notes, making it sufficiently complete. It could mention potential side-effects or edge cases, but for this tool's simplicity, the coverage is strong.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 100%, so the parameters are fully documented in the input schema. The description adds only minor context like 'Short label' for text, which is already implied. It does not provide additional semantic value beyond the schema, earning the baseline score of 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Show or update a status readout in the notch.' It uses a specific verb ('Show or update') and resource ('status readout in the notch'), and distinguishes it from siblings like notch_done and notch_error by instructing to finish with those tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit when-to-use guidance: 'Call when starting long-running work and again as it progresses.' It also provides a clear follow-up instruction to always finish with notch_done or notch_error. However, it does not explicitly state when not to use this tool or recommend alternatives for other scenarios.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

notch_stylesA

List the available notch readout styles with metadata on what each is for, plus the current display capability. Call this once before your first notch_status if you are unsure which style fits, or to check whether this Mac currently has a notch at all.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden of behavioral disclosure. It clarifies that the tool is a read-only listing/check operation with no side effects, and adds the context that it should be called before first use if needed. It could have explicitly stated it makes no changes, but 'List' and 'check' strongly imply safety.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, with the purpose front-loaded and usage guidance immediately following. Every word adds value with no redundancy or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a no-parameter listing tool, the description provides complete context: what it lists, why it's useful, and when to call it. The absence of an output schema is fine because the tool's purpose is self-explanatory and the sibling tools provide surrounding context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the description doesn't need to elaborate on schema items. The baseline for 0 params is 4, and the description correctly focuses on what the tool does rather than parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool 'List[s] the available notch readout styles with metadata' and also mentions checking 'current display capability.' It specifies a distinct resource and action, distinguishing it from sibling tools like notch_status or notch_clear.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit guidance is provided: 'Call this once before your first notch_status if you are unsure which style fits, or to check whether this Mac currently has a notch at all.' This tells the agent exactly when to invoke this tool and implies alternatives (e.g., use notch_status after choosing a style).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

5 tool updatesv1.0.0Aug 3, 2026
- First observednotch_clear
- First observednotch_done
- First observednotch_error
- First observednotch_status
- First observednotch_styles

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.2/5.0

Scored 2026-08-03 01:15 across 5 tools

Disambiguation5/5

Each tool has a distinct purpose: listing styles, setting a status, marking success, marking failure, and clearing. There is no overlap or ambiguity between them.

Naming Consistency4/5

All tools share the 'notch_' prefix and use simple, readable lowercase names. However, the pattern is not strictly verb_noun (e.g., 'styles' is a noun, 'done' is an adjective), so there is a minor deviation from a consistent verb-first convention.

Tool Count5/5

Five tools is exactly right for this server's scope. Each tool fills a necessary role in the lifecycle of displaying and resolving notch readouts without redundancy.

Completeness5/5

The tool set covers the full lifecycle: checking capability, showing/updating a status, and resolving as success, failure, or immediate clear. There are no obvious missing operations for the stated purpose.

Maintenance

ActivitySlowing

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

kweenkl-mcp A
io.github.antoinedelorme
Push notifications for AI agents - send instant iPhone notifications from any MCP client.
Communication App Automation
62
Yo A
io.github.alfongj-com
Let agents send content-free push notifications to a paired phone via MCP.
Communication App Automation
51
CapabilityWire A
io.github.jawauntb
A live, curated feed of new AI agent capabilities across MCP, SDKs, models, and APIs.
AI & Machine Learning Agent Orchestration Developer Tools
41
messages-bridgeOAuth
io.github.IsaiahDupree
MCP connector for iMessage & Contacts via a local Mac agent + Vercel relay
Communication App Automation
1

Related MCP Servers

MCP Notifications Server
OS Automation App Automation
konstzv
F
license
B
quality
D
maintenance
Enables Claude and other MCP clients to display native macOS notifications with customizable titles, messages, icons, and sounds through the macOS Notification Center.
Updated 9 months ago (2025-12-19 00:45 UTC)
1
5 npm
-
mcp-notifications
Developer Tools
Artemeey
A
license
D
quality
D
maintenance
Enables MCP agents to send desktop notifications for completed tasks, failures, and important updates, providing visible and reliable feedback.
Updated 4 months ago (2026-05-17 18:12 UTC)
1
39 npm
2
Apache 2.0
mcp-ding
OS Automation Developer Tools
zhuqingyv
F
license
Not graded
quality
D
maintenance
MCP server for macOS native notifications with 67 AI brand icons and system sound support, enabling AI agents to send desktop notifications via one-line tool calls.
Updated 6 months ago (2026-04-07 06:41 UTC)
-
macOS Companion MCP Server
OS Automation Communication Entertainment & Media
surendranb
A
license
B
quality
A
maintenance
Enables AI agents to directly access native macOS services, media, system health, and administration tools through a local MCP server.
Updated 23 days ago (2026-09-01 00:43 UTC)
40
13 npm
MIT