# ScreenBlurt for agents (MCP)

ScreenBlurt is a Mac menu-bar app that reads text aloud. It ships an MCP
server inside the app, so you can speak to the user through it. This page
tells you how to connect. Follow the steps in order.

## 1. Check the app is installed

The server is the app's own binary launched with `--mcp`. Nothing else to
install. It needs ScreenBlurt 1.1 or later at:

    /Applications/ScreenBlurt.app

Check it exists and read the version:

    defaults read "/Applications/ScreenBlurt.app/Contents/Info.plist" CFBundleShortVersionString

If the app is missing or older than 1.1, stop and tell the user to
install or update it from https://github.com/justinjordan/screenblurt/releases/latest
then come back to this page. Do not try to build or download it yourself.

## 2. Work out which MCP client you are

You are one of the clients below, or something like them. Pick the matching
install step. Every option registers the same stdio server: command
`/Applications/ScreenBlurt.app/Contents/MacOS/ScreenBlurt`, one argument `--mcp`, name `screenblurt`.

### Claude Code

    claude mcp add --scope user screenblurt -- "/Applications/ScreenBlurt.app/Contents/MacOS/ScreenBlurt" --mcp

User scope, so it follows the user between projects. Confirm with
`claude mcp list` or `/mcp`.

### Codex

    codex mcp add screenblurt -- "/Applications/ScreenBlurt.app/Contents/MacOS/ScreenBlurt" --mcp

Or add this to `~/.codex/config.toml`:

```toml
[mcp_servers.screenblurt]
command = "/Applications/ScreenBlurt.app/Contents/MacOS/ScreenBlurt"
args = ["--mcp"]
```

### Claude Desktop

Merge this into `~/Library/Application Support/Claude/claude_desktop_config.json`
(create the file if it does not exist, keep any servers already in it), then
tell the user to quit and reopen Claude Desktop:

```json
{
  "mcpServers": {
    "screenblurt": {
      "command": "/Applications/ScreenBlurt.app/Contents/MacOS/ScreenBlurt",
      "args": ["--mcp"]
    }
  }
}
```

### Cursor

Merge the same JSON into `~/.cursor/mcp.json` (or the project's
`.cursor/mcp.json`). Cursor picks it up without a restart.

### Windsurf

Merge the same JSON into `~/.codeium/windsurf/mcp_config.json`, then refresh
MCP servers from the Cascade panel.

### VS Code (Copilot)

    code --add-mcp '{"name":"screenblurt","command":"/Applications/ScreenBlurt.app/Contents/MacOS/ScreenBlurt","args":["--mcp"]}'

### Anything else

It is a plain stdio MCP server. Use your client's usual way to add one:
command `/Applications/ScreenBlurt.app/Contents/MacOS/ScreenBlurt`, args `["--mcp"]`.

## 3. Expect an Allow / Deny prompt

The first time your client connects, ScreenBlurt shows the user a prompt:
"<your client name> wants to speak through ScreenBlurt", with Allow and
Deny. Tell the user to click Allow. Until they answer, tool calls return an
error saying so. If the user denied, they can change it in Settings → Agents.

If the app is not running, the bridge launches it and waits up to 15 seconds.

## 4. Test it

Reconnect or restart your MCP session so the new server is loaded, then call
`status` (free) to confirm the user is signed in, and `speak` with a short
greeting, for example "ScreenBlurt is connected." If `speak` fails with a
logged-out or out-of-credits error, relay that message to the user; it tells
them what to do.

## 5. Using it well

- Every `speak` call spends the user's ScreenBlurt character allowance:
  1 character per character at Standard, 2.5x at HQ. Keep messages short and
  conversational, a sentence or two. Do not read code, logs, diffs, or long
  documents aloud unless the user asked for exactly that.
- Text is capped at 4,096 characters. Anything longer is cut and the result
  says so.
- `speak` returns when playback starts. Pass `wait: true` to return when it
  finishes. `stop` closes reads you started. `status` is free.
- Use `speak` when the user asked to be spoken to, or when a short spoken
  heads-up is genuinely useful (a long task finished, a question needs them).

Human-readable version: https://screenblurt.com/agents