Speak MCP

A local MCP server that rewrites text with Ollama for natural speech and reads it aloud with macOS say.

Requirements

• macOS with the say command available.
• Node.js 18 or newer.
• Ollama running locally.
• The configured Ollama model pulled locally.

Installation

You do not need to clone this repository to use Speak MCP. Install the published npm package globally, then configure your MCP client to run the speak-mcp binary.

npm install -g @rxreyn3/speak-mcp

Claude Desktop configuration

Edit ~/Library/Application Support/Claude/claude_desktop_config.json and add this server under mcpServers:

{
  "mcpServers": {
    "speak": {
      "command": "speak-mcp",
      "env": {
        "OLLAMA_HOST": "http://localhost:11434",
        "OLLAMA_MODEL": "qwen2.5:7b-instruct"
      }
    }
  }
}

Restart Claude Desktop after changing the config.

Local development

For local development from a clone:

npm install
npm run build

Then point your MCP client at the built entrypoint:

{
  "mcpServers": {
    "speak": {
      "command": "node",
      "args": ["/absolute/path/to/speak-mcp/dist/index.js"],
      "env": {
        "OLLAMA_HOST": "http://localhost:11434",
        "OLLAMA_MODEL": "qwen2.5:7b-instruct"
      }
    }
  }
}

Tools

speak_text

Reads explicit text aloud. The MCP client must pass the text; this server cannot read the client transcript itself.

{ "text": "Text to read aloud" }

The server rewrites the text with Ollama before playback. If Ollama is unreachable, returns an MCP tool error and does not speak raw text.

stop_speech

Stops the current macOS say playback, if any. This tool does not contact Ollama and does not start replacement audio.

Prompt

The server registers read_aloud, a user-selected prompt that instructs an MCP client to call speak_text with visible assistant response text when read-aloud behavior is requested.

Troubleshooting

• If Claude Desktop does not show the server, confirm Node.js 18+ is installed and restart Claude Desktop after editing the config.
• If speech does not start, confirm Ollama is running at OLLAMA_HOST and the model in OLLAMA_MODEL is pulled.
• Do not add console.log to the server: stdout is reserved for MCP JSON-RPC messages. Use console.error for diagnostics.
• Late say playback failures are logged to stderr and MCP logging; there is intentionally no speech_status tool in v1.