isimud

isimud is a macOS menu bar app and streamable-HTTP MCP server that lets AI agents speak. An agent sends text to an MCP tool; isimud resolves a named voice, synthesizes speech through Apple, OpenAI, or Google, then plays it through a single serialized speech queue.

isimud is the text-to-speech counterpart to muninn, which turns speech into text for agents.

Use isimud when you want:

• A local macOS tray app that pulses while an agent is speaking.
• A headless MCP server for scripted or background use.
• Local-first text-to-speech with optional bring-your-own-key cloud providers.
• Named voices that hide provider-specific voice IDs from agents.
• Queueing, cancellation, status, and speech lifecycle notifications over MCP.

Quickstart

Complete this path to run isimud with the local Apple text-to-speech provider. Apple TTS does not require an API key.

Prerequisites

• macOS. The project is macOS-only; the packaged app declares macOS 12.0 or newer.
• Rust 1.89 or newer and Cargo.
• An MCP client that supports streamable HTTP.

Install

Install the published binary crate:

cargo install isimud-text-to-speech

Verify that Cargo installed the `isimud` binary:

isimud --version

Or build from this repository:

cargo build --release --bin isimud
./target/release/isimud --version

Configure

isimud creates a launchable default config on first run if no config file exists. That generated config contains a single Apple-backed `default` voice. To start from the full sample config instead, create the config directory and copy the sample:

mkdir -p ~/.config/isimud
cp configs/config.sample.toml ~/.config/isimud/config.toml

Config path precedence is:

1. `ISIMUD_CONFIG`

2. `$XDG_CONFIG_HOME/isimud/config.toml`

3. `~/.config/isimud/config.toml`

Run

Start the menu bar app and MCP server:

isimud

For server-only operation:

isimud --headless

CLI options:

--headless     Run only the MCP server
-h, --help     Print help
-V, --version  Print the version

Expected result:

• In menu bar mode, a small isimud indicator appears in the macOS menu bar.
• The MCP server listens on `http://127.0.0.1:3654/mcp`.
• Calling `isimud.status` from your MCP client returns `state: "idle"` when nothing is speaking.

Connect an MCP client

Configure your MCP client with streamable HTTP transport:

URL: http://127.0.0.1:3654/mcp

If you set `ISIMUD_AUTH_TOKEN` or `[server].auth_token`, add this request header:

Authorization: Bearer

The server only binds to loopback IP addresses. `127.0.0.1` and `::1` are accepted; hostnames such as `localhost` and non-loopback addresses such as `0.0.0.0` are rejected at startup.

When auth is configured, requests without the exact bearer token return HTTP `401`.

Speak from an agent

Call `isimud.speak` with text:

{
  "text": "Build finished.",
  "voice": "default",
  "rate": 1.0
}

The call returns immediately by default:

{
  "job_id": "00000000-0000-0000-0000-000000000000",
  "queue_depth": 0
}

Set `wait` to `true` when the MCP caller should block until the utterance completes, fails, is cancelled, or reaches `[tts].wait_timeout_secs`:

{
  "text": "Deployment complete.",
  "wait": true
}

With `wait=true`, the response includes `outcome`:

{
  "job_id": "00000000-0000-0000-0000-000000000000",
  "queue_depth": 0,
  "outcome": "completed"
}

Configure voices and providers

Named voices are the public voice contract for agents. The `voice` argument to `isimud.speak` and `[tts].default_voice` must match a `[voices.]` key.

[tts]
providers = ["apple", "openai", "google"]
default_voice = "default"
rate = 1.0
max_queue_depth = 64
wait_timeout_secs = 0

[voices.default]
provider = "apple"
voice = "Samantha"

[voices.narrator]
provider = "openai"
voice = "onyx"

[voices.googler]
provider = "google"
voice = "en-US-Neural2-C"
language = "en-US"

Important: `default_voice` is a voice name, not a provider name. To make OpenAI the default, set `default_voice = "narrator"` or create another `[voices.]` block whose `provider = "openai"`.

Optional per-voice fields are `language`, `rate`, `pitch`, and `volume`. A request `rate` overrides the voice `rate`, which overrides `[tts].rate`; voice `volume` defaults to `1.0`.

Provider availability follows `[tts].providers`. If the requested voice's provider is unavailable, isimud selects the first available fallback provider and drops the provider-specific voice ID for that fallback utterance. If no provider is available, the job fails and emits a `failed` event.

Provider setup

OpenAI and Google send a rate/speed value only when the resolved rate is within `0.25..=4.0`. Google sends pitch only when the resolved pitch is within `-20..=20`.

OpenAI built-in voice IDs exposed by `isimud.list_voices`:

alloy ash ballad cedar coral echo fable marin nova onyx sage shimmer verse

Google voice listing is intentionally best-effort and currently returns an empty provider catalog; configured named Google voices still work.

Configuration reference

See configs/config.sample.toml for the full sample.

The TOML schema is strict. Unknown fields fail config parsing; hot reload keeps the previous config when a changed file fails to parse or validate.

Environment variables:

Shell environment variables win over `.env` and config-file secrets.

MCP tool reference

`isimud.speak` rejects empty text and unknown named voices as invalid parameters. When the queue is full, it returns JSON-RPC error code `-32010` with this data payload:

{
  "queue_depth": 64,
  "capacity": 64
}

Connected MCP peers receive `isimud/speech_event` custom notifications for these lifecycle events:

enqueued started finished failed stopped degraded

Custom MCP requests named `isimud/quit` or `isimud/exit` trigger graceful shutdown.

Runtime behavior

isimud runs one speech worker. Jobs never overlap; each accepted utterance waits for the current utterance to finish or be cancelled.

The active job does not count toward `[tts].max_queue_depth`. That setting only limits jobs waiting behind the active utterance.

Saving the config file hot-reloads the speech engine and tray palette. Valid changes update voices, provider credentials, speaking rates, queue settings, and tray colors without a restart. Invalid edits are logged and the previous config stays active.

Server bind settings (`[server].host`, `[server].port`, `[server].path`, and auth) and LaunchAgent autostart sync are applied at startup. Restart isimud after changing those settings.

The macOS tray icon is gray while idle and pulses green while speaking. If the speech worker exits unexpectedly or a job panics, `isimud.status` reports `degraded: true` and a `degraded` event is broadcast.

macOS app features

URL scheme

The packaged app registers the `isimud://` URL scheme. Use it to enqueue speech from macOS links or automation:

isimud://speak/Hello%20world
isimud://speak?text=Hello%20world&voice=narrator&rate=1.25

The path text takes precedence over the `text` query parameter when both are present. The URL scheme is available when running the packaged `.app` that includes the `CFBundleURLTypes` entry.

Tray click

In menu bar mode, a left click on the tray icon tries to run the optional `fortune` command and speak its output. If `fortune` is not installed or returns no text, the click is ignored and a warning is logged.

Autostart

Set `[app].autostart = true` to sync a per-user LaunchAgent at `~/Library/LaunchAgents/com.bnomei.isimud.plist`. The LaunchAgent uses the current executable path and sets `ISIMUD_CONFIG` to the resolved config path.

When running the packaged `.app`, prefer macOS Login Items if you want app-style launch behavior.

Packaging

Build a release binary for a target:

TARGET=aarch64-apple-darwin scripts/build-release.sh

Build a macOS app bundle and zip archive from an existing release binary:

TARGET=aarch64-apple-darwin scripts/package-macos-app.sh

If you built the default host target with `cargo build --release --bin isimud`, run `scripts/package-macos-app.sh` without `TARGET`.

Useful packaging variables:

Create a tarball release archive from a built target:

VERSION=$(scripts/resolve-version.sh) TARGET=aarch64-apple-darwin scripts/package-release.sh

Development

Run the main checks:

cargo test
cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings

This repository also includes prek hooks:

prek install
prek run --all-files

Current limits

• macOS is the only supported platform.
• The MCP server supports streamable HTTP only; there is no stdio transport.
• The server binds only to loopback addresses.
• Apple `say` honors `rate` but does not apply `volume` or `pitch`.
• OpenAI and Google request timeouts are left to the HTTP client and provider/network behavior. `[tts].wait_timeout_secs` only limits how long an MCP `wait=true` call waits for the job outcome; it does not cancel synthesis.
• isimud validates that `text` is non-empty, but it does not enforce a fixed character, byte, token, or provider response-size limit.
• Cloud-provider audio is decoded and played in memory, so very long utterances can increase memory use and playback latency.

Source map

• Configuration loading and defaults: src/config.rs
• MCP tools and notification fan-out: src/mcp.rs
• HTTP server and loopback/auth enforcement: src/server.rs
• Named voice resolution: src/voices.rs
• Speech queue and worker: src/worker.rs
• Provider registry and fallback: src/providers/mod.rs
• macOS tray behavior: src/runtime_tray.rs
• URL scheme parsing: src/url_scheme.rs
• macOS app bundle template: packaging/macos/Info.plist.template

License

MIT. See LICENSE.