# Brainiall TTS MCP Server

Hosted text-to-speech for AI agents via the [Model Context Protocol](https://modelcontextprotocol.io).

**54 neural voices, 9 languages** — including native **Brazilian Portuguese** (`pf_dora`, `pm_alex`, `pm_santa`) — served from a hosted, pay-per-use API. No GPU, no model downloads, no ElevenLabs subscription: bring one API key and pay **$0.008 per 1,000 characters** ($10 free credits on signup).

## Why this server

Every other TTS MCP server either runs models locally (heavy, slow to set up) or wraps a third-party key you already pay a subscription for. This one is a hosted, metered API:

- **Zero setup** — remote server, nothing to install
- **Pay per use** — $0.008/1K characters, billed against your Brainiall balance
- **$10 free credits** — sign up at [app.brainiall.com](https://app.brainiall.com)
- **WAV out** — 16-bit PCM, 24 kHz mono, returned as playable MCP audio content or base64 JSON

## Quick start

Get an API key at [app.brainiall.com](https://app.brainiall.com?utm_source=github&utm_medium=oss&utm_campaign=tts_mcp) ($10 welcome credits, no card required).

### VS Code / GitHub Copilot

[![Install Brainiall TTS in VS Code](https://img.shields.io/badge/VS_Code-Install_Brainiall_TTS-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=brainiall-tts&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fapi.brainiall.com%2Fmcp%2Ftts%2Fmcp%22%7D)

The button installs the remote server in discovery mode, so VS Code can list its tools without a secret. Synthesis still fails closed until you add your Brainiall API key. For a secure workspace configuration that prompts once and stores the key in VS Code's secret storage, copy [`.vscode/mcp.json`](.vscode/mcp.json) into your project or clone this repository, then start `brainiallTts` from **MCP: List Servers**.

```json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "brainiall-api-key",
      "description": "Brainiall API key",
      "password": true
    }
  ],
  "servers": {
    "brainiallTts": {
      "type": "http",
      "url": "https://api.brainiall.com/mcp/tts/mcp",
      "headers": {
        "Authorization": "Bearer ${input:brainiall-api-key}"
      }
    }
  }
}
```

After the server starts, try:

> Use Brainiall TTS to list the Brazilian Portuguese voices, then read “Olá do VS Code” with `pf_dora`.

The install URL format and secret-input configuration follow the [official VS Code MCP guide](https://code.visualstudio.com/api/extension-guides/ai/mcp) and [configuration reference](https://code.visualstudio.com/docs/agents/reference/mcp-configuration).

### GitHub Copilot cloud agent

Use the [restricted remote-server configuration](examples/github-copilot-cloud/README.md) for Copilot cloud agent or Copilot code review. It allowlists the three Brainiall tools and resolves the Bearer token from the repository's `COPILOT_MCP_BRAINIALL_API_KEY` Agents secret; no API key is committed.

### Continue (VS Code / JetBrains)

Copy the ready-to-use [Continue MCP block](examples/continue/brainiall-tts.yaml)
to `.continue/mcpServers/brainiall-tts.yaml`, then put
`BRAINIALL_API_KEY=your-key` in `.continue/.env`. Keep that `.env` file out
of version control.

The block uses Continue's supported `streamable-http` transport and resolves
the key through `${{ secrets.BRAINIALL_API_KEY }}`; no credential is committed.
See the [Continue setup and smoke test](examples/continue/README.md).

### Dify builders

For a Dify speech workflow, use the open-source [BRAINIALL Speech provider](https://github.com/fasuizu-br/brainiall-dify-provider) and keep the API key in Dify's credential store. The [bounded Dify intent route](https://www.brainiall.com/transcreve/integracoes/dify-transcreve-ptbr-pipeline) explains the caller-owned boundary; it is not a Dify partnership or a guarantee of production behavior.

### Remote server (recommended — nothing to install)

**Codex CLI / IDE / ChatGPT desktop app**

Use the [project-scoped Codex configuration](examples/codex/README.md). It reads
`BRAINIALL_API_KEY` from the environment, allowlists the three Brainiall tools,
and prompts before every call.

**Claude Code**

Use the [environment-backed Claude Code configuration](examples/claude-code/README.md). It keeps the key out of `.mcp.json`, scopes the server to the current project, and documents the external-data and metered-usage boundary.

**Claude Desktop / any client with `.mcp.json`-style config**

```json
{
  "mcpServers": {
    "brainiall-tts": {
      "type": "http",
      "url": "https://api.brainiall.com/mcp/tts/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_BRAINIALL_API_KEY"
      }
    }
  }
}
```

**Cursor** (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "brainiall-tts": {
      "url": "https://api.brainiall.com/mcp/tts/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_BRAINIALL_API_KEY"
      }
    }
  }
}
```

**LM Studio**

Use the official one-click deeplink and the explicit local-model privacy boundary in the [LM Studio setup guide](examples/lm-studio/README.md).

**OpenCode v2**

Use the remote-server schema and environment-backed Bearer header in the [OpenCode v2 setup guide](examples/opencode/README.md).

**Msty Studio**

Use the [manual Msty Studio field guide](examples/msty/README.md) for a
Streamable HTTP connection. The reference file is not presented as an
official integration or import preset.

**Hugging Face Chat UI (self-hosted)**

Use the [administrator `MCP_SERVERS` example](examples/hugging-face-chat-ui/README.md)
and a tool-capable model. The guide documents the shared-key boundary for base
servers.

### Clients that require `/v1/audio/speech`

Use the zero-dependency [partial OpenAI-shaped TTS adapter](examples/openai-compatible-tts-adapter/README.md)
when a client can configure an OpenAI-style speech route but cannot call
Brainiall's native endpoint. The adapter returns WAV only, declares the sample
rate observed in the WAV header, never retries a metered request, and documents
the exact compatibility limits. It is a local reference adapter, not a claim
that the hosted Brainiall API is natively OpenAI-compatible.

### Run locally (stdio-free, still calls the hosted API)

The server itself is a thin wrapper — you can self-host it and it will proxy to `api.brainiall.com` with your key:

```bash
docker build -t brainiall-tts-mcp .
docker run -p 8080:8080 -e APIM_KEY=YOUR_BRAINIALL_API_KEY brainiall-tts-mcp
# MCP endpoint: http://localhost:8080/mcp
```

## Tools

| Tool | Description | Cost |
|------|-------------|------|
| `synthesize_speech` | Convert text (≤5000 chars) to WAV speech. Params: `text`, `language` (default `pt`), `voice`, `speed` (0.5–2.0), `output_format` (`audio` \| `base64_json`) | $0.008/1K chars |
| `list_voices` | Full voice catalog with language, gender, accent, quality grade. Optional `language` filter | free |
| `check_tts_service` | Backend health status | free |

### Voices

| Language | Voices |
|----------|--------|
| Portuguese (BR) | `pf_dora`, `pm_alex`, `pm_santa` |
| English (US) | `af_heart`, `af_bella`, `af_nova`, `am_adam`, `am_michael` + 14 more |
| English (GB) | `bf_alice`, `bf_emma`, `bm_daniel`, `bm_george` + 4 more |
| Spanish | `ef_dora`, `em_alex`, `em_santa` |
| French | `ff_siwis`, `fm_gilles` |
| Italian | `if_sara`, `im_nicola` |
| Hindi | `hf_alpha`, `hf_beta`, `hm_omega`, `hm_psi` |
| Japanese | `jf_alpha`, `jf_gongitsune`, `jm_kumo` + 2 more |
| Mandarin | `zf_xiaoxiao`, `zm_yunxi` + 6 more |

### Example

Ask your agent:

> "Read this paragraph out loud in Brazilian Portuguese with a female voice"

The agent calls `synthesize_speech(text=..., language="pt", voice="pf_dora")` and receives playable WAV audio.

For copy-ready prompts and smoke tests for narration, accessibility, language practice, and agent alerts, see [Agent workflow recipes](examples/agent-workflows.md).

For REST client testing and automation, import the [Postman collection](postman/Brainiall-TTS-API.postman_collection.json). It contains health, voice-list and two-character synthesis smoke tests and keeps the API key in a collection variable rather than the request URL.

For no-code automation, import the [n8n text-to-WAV workflow](examples/n8n-brainiall-tts-to-wav.json). It uses n8n's Header Auth credential instead of embedding a key in the workflow, sends editable text, voice and speed fields to the hosted API, and returns the WAV in the binary property `speech`. The template is statically validated; select your credential and run it in your own n8n instance to validate the live integration.

For code generation, API clients, and directory discovery, use the machine-readable [OpenAPI 3.1 specification](openapi/brainiall-tts.openapi.yaml). The specification documents the authenticated voice catalog and WAV synthesis endpoints without embedding an API key.

## Authentication & billing

Pass your Brainiall API key as a Bearer token (see configs above). Usage is metered per character against your account balance — the same key works across all Brainiall APIs (STT, OCR, NLP, image and more at [brainiall.com](https://brainiall.com)).

## Endpoints

- MCP (Streamable HTTP): `https://api.brainiall.com/mcp/tts/mcp`
- Health: `https://api.brainiall.com/mcp/tts/health`
- Underlying REST API: `POST https://api.brainiall.com/v1/tts/synthesize`

## License

MIT