Connect YazSes to an MCP client¶

yazses mcp-server is an MCP server. An MCP client, such as Claude Desktop, Claude Code or an editor with MCP support, starts it as a child process and talks to it over stdin and stdout. It opens no network port, and transcription runs on your machine.

It offers two tools:

ask_human needs the YazSes daemon running (yazses start). An hourly budget limits how often agents may interrupt you, and your answer goes back to the agent, never into the window you had open. See the CLI reference for the details.

Install YazSes first. Every route below runs the yazses command already installed on your machine. None of them installs YazSes for you. If you have not installed it, start with Get started, and check that yazses --version works in a terminal.

Route 1: the one-click bundle (.mcpb)¶

An MCP Bundle is a single file a desktop client installs by double-click or drag-and-drop. The YazSes bundle, yazses-<version>.mcpb, contains no copy of YazSes: it tells the client to run yazses mcp-server, so your model, your settings and your microphone permission stay with the install you already have.

1. Get the bundle. It ships from the next release after v2.44.0 on: download yazses-<version>.mcpb from the GitHub release, where it sits beside the other downloads. Each release builds it from its own tagged source, lists it in SHA256SUMS.txt, and attaches its build provenance as yazses-<version>-mcpb.intoto.jsonl. You can check both as Code signing & verification describes. v2.44.0 and earlier releases do not include it. For those, build it from a checkout of the repository with python3 scripts/build-mcpb.py. The file is written to dist/.
2. Open the file with your client: double-click it, or drag it onto the client's extension settings.
3. Restart the client if it asks you to, then check that the YazSes tools appear.

The bundle has not yet been tried in a real client, so if a step above does not match what your client shows, please open an issue.

Route 2: add it to the client's configuration by hand¶

This works with any MCP client. The server entry is:

{"command": "yazses", "args": ["mcp-server"]}

Clients that use an mcpServers map, such as Claude Desktop's claude_desktop_config.json, take it under a name of your choice:

{
  "mcpServers": {
    "yazses": {"command": "yazses", "args": ["mcp-server"]}
  }
}

With Claude Code, one command does the same:

claude mcp add yazses -- yazses mcp-server

Route 3: the MCP registry¶

The official MCP registry lists servers that clients can search for. YazSes is not listed yet. Once it is, it will appear as io.github.MSKazemi/yazses, pointing at the yazses package on PyPI with the argument mcp-server.

A client that installs from the registry may fetch its own copy of the yazses package, for example with uvx, rather than use the one you installed. That copy reads the same config.toml, but it can be a different version, and it has none of the optional features you added to your own install, such as another speech engine. To use the install you already have, prefer route 1 or route 2.

If the client says yazses was not found¶

A desktop app started from the Dock, the Start menu or an application launcher does not always see the same PATH as your terminal. This is common on macOS when YazSes was installed with pipx or uv tool, which put yazses in ~/.local/bin.

Use the full path instead. Run which yazses (macOS, Linux) or where yazses (Windows) in a terminal, and put the result in the command field of route 2, for example {"command": "/Users/you/.local/bin/yazses", "args": ["mcp-server"]}. The bundle in route 1 always uses the bare yazses command, so this fix needs route 2.

Turn on ask_human¶

ask_human is off by default and not listed until you turn it on. Add this to your YazSes config.toml, then restart the MCP client so it starts a new server:

[mcp]
ask_human = true
ask_human_per_hour = 3   # spoken questions allowed per hour, shared by every agent