langlearn-tts 0.3.1

TTS MCP server and CLI for language learning (AWS Polly, OpenAI)

langlearn-tts

Generate audio flashcards and vocabulary drills from text. Ask Claude to synthesize words and phrases in any language, or batch-process entire vocabulary lists from the command line. Audio is slowed to 90% speed by default so learners can hear pronunciation clearly.

The pair mode is the core workflow: give it an English word and its translation, and it produces a single MP3 — [English audio] [pause] [target language audio] — ready for Anki, spaced repetition, or passive listening.

Available as both a Claude Desktop MCP server (ask Claude to generate audio in conversation) and a CLI with identical functionality. Supports AWS Polly and OpenAI TTS today; ElevenLabs is planned.

Features

• Single synthesis — convert text to MP3 in any supported language
• Batch synthesis — synthesize multiple texts, optionally merged into one file
• Pair synthesis — stitch two languages together: [English] [pause] [L2]
• Pair batch — batch-process vocabulary lists as stitched pairs
• Auto-play — MCP tools play audio immediately after synthesis
• Configurable speech rate — default 90% for learner-friendly pacing
• Two providers — AWS Polly (93 voices, 41 languages) or OpenAI TTS (9 voices, 57 languages)
• Auto-detection — defaults to OpenAI when OPENAI_API_KEY is set, otherwise Polly

Quick Start

1. Install uv (Python package manager)

If you don't have uv yet:

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

uv manages Python versions automatically — you don't need to install Python separately.

2. Install langlearn-tts

uv tool install langlearn-tts

This installs the langlearn-tts CLI and langlearn-tts-server MCP server globally.

3. Install ffmpeg

Required for audio stitching (pairs, merged batches). Single synthesis works without it.

# macOS (requires Homebrew — install from https://brew.sh if needed)
brew install ffmpeg

# Ubuntu/Debian
sudo apt install ffmpeg

# Windows
winget install ffmpeg

4. Configure a TTS provider

Pick one provider. The tool auto-detects which to use: if OPENAI_API_KEY is set, it uses OpenAI; otherwise it uses Polly. You can override with --provider polly or --provider openai.

Option A — OpenAI TTS (simplest):

export OPENAI_API_KEY=sk-...

9 built-in voices, 57 languages. Pricing: $15/1M characters (tts-1) or $30/1M (tts-1-hd).

Option B — AWS Polly:

Requires an AWS account with polly:SynthesizeSpeech and polly:DescribeVoices permissions.

Install the AWS CLI, then:

aws configure

Enter your Access Key ID, Secret Access Key, and region (e.g., us-east-1). Alternatively, set AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_DEFAULT_REGION environment variables.

5. Verify

langlearn-tts doctor

All required checks should show ✓. Fix any that show ✗ before continuing.

From source (development)

git clone https://github.com/jmf-pobox/langlearn-tts-mcp.git
cd langlearn-tts-mcp
uv sync --all-extras
uv run langlearn-tts --help

Claude Desktop Setup

Automatic (recommended)

langlearn-tts install

This registers the MCP server with Claude Desktop. It auto-detects your provider and writes the necessary env vars (including OPENAI_API_KEY for OpenAI) into the config.

Options:

• --provider NAME — force a provider (polly or openai) instead of auto-detecting
• --output-dir PATH — custom audio output directory (default: ~/Claude-Audio)
• --uvx-path PATH — override the uvx binary path

Restart Claude Desktop after running install.

Manual

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "langlearn-tts": {
      "command": "/absolute/path/to/uvx",
      "args": ["--from", "langlearn-tts", "langlearn-tts-server"],
      "env": {
        "LANGLEARN_TTS_PROVIDER": "openai",
        "OPENAI_API_KEY": "sk-...",
        "LANGLEARN_TTS_OUTPUT_DIR": "/absolute/path/to/output/directory"
      }
    }
  }
}

Claude Desktop does not inherit your shell environment. All paths must be absolute and API keys must be literal values in the config. Find your uvx path with which uvx.

Env var	Required	Description
LANGLEARN_TTS_PROVIDER	No	openai or polly. Auto-detects if omitted.
OPENAI_API_KEY	For OpenAI	Your literal API key (Claude Desktop does not support env var references)
LANGLEARN_TTS_OUTPUT_DIR	No	Output directory (default: ~/Claude-Audio)
LANGLEARN_TTS_MODEL	No	OpenAI model (tts-1, tts-1-hd). Default: tts-1

For Polly, omit OPENAI_API_KEY and set LANGLEARN_TTS_PROVIDER to polly. AWS credentials are read from ~/.aws/credentials.

Restart Claude Desktop after editing the config.

AI Tutor Prompts

langlearn-tts ships with 28 ready-made AI tutor prompts — one for each combination of 7 languages and 4 levels. Paste a prompt into a Claude Desktop Project's Instructions field, and Claude becomes a language tutor that generates audio during lessons.

Browse prompts

# List all available prompts
langlearn-tts prompt list

# Print a prompt (pipe to clipboard with pbcopy on macOS)
langlearn-tts prompt show german-high-school | pbcopy

Set up a Claude Desktop Project

1. In Claude Desktop, click Projects in the sidebar
2. Click Create Project and name it (e.g., "German with Herr Schmidt")
3. Open the project, click Set custom instructions
4. Paste the prompt content into the Instructions field
5. Start a new conversation within that project

Using a Project keeps the tutor persona scoped to language learning. Other conversations are unaffected.

Available languages and levels

Language	High School	1st Year	2nd Year	Advanced
German	Herr Schmidt	Professorin Weber	Professor Hartmann	Professor Becker
Spanish	Profesora Elena	Profesor Garcia	Profesora Carmen	Profesora Reyes
French	Madame Moreau	Professeur Laurent	Professeur Dubois	Professeur Beaumont
Russian	Irina Petrovna	Professor Dmitri	Professor Natasha	Professor Mikhail
Korean	Kim-seonsaengnim	Professor Park	Professor Kim	Professor Yoon
Japanese	Tanaka-sensei	Yamamoto-sensei	Suzuki-sensei	Mori-sensei
Chinese	Laoshi Wang	Professor Chen	Professor Zhang	Professor Wei

Each prompt creates a tutor persona calibrated to the student's level, based on Mollick & Mollick's "Assigning AI" framework. Customize any prompt by adjusting student background, voice selection, speech rate, or focus areas.

Troubleshooting

langlearn-tts doctor

Checks Python version, active provider, ffmpeg, provider-specific credentials, uvx, Claude Desktop config, and output directory. Required checks must pass (exit code 1 on failure); optional checks show ○ markers.

Voices

OpenAI TTS

9 built-in voices. Voice names are case-insensitive.

Voice	Description
alloy	Neutral, balanced
ash	Warm, conversational
coral	Clear, expressive
echo	Smooth, authoritative
fable	Warm, British-accented
onyx	Deep, resonant
nova	Friendly, upbeat
sage	Calm, measured
shimmer	Light, gentle

Select the model with --model tts-1 (faster, cheaper) or --model tts-1-hd (higher quality).

AWS Polly

Any voice from the AWS Polly voice list is supported. Voice names are case-insensitive. The tool queries the Polly API on first use and caches the result.

Common voices for language learning:

Voice	Language	Engine
joanna	English (US)	neural
matthew	English (US)	neural
daniel	German	neural
vicki	German (female)	neural
lucia	Spanish (European)	neural
lupe	Spanish (US)	neural
léa	French	neural
tatyana	Russian	standard
seoyeon	Korean	neural
takumi	Japanese	neural
zhiyu	Chinese (Mandarin)	neural

The engine (neural, standard, generative, long-form) is selected automatically — neural preferred when available.

CLI Usage

# Single synthesis
langlearn-tts synthesize "Guten Morgen" --voice daniel -o morning.mp3

# Custom speech rate (percentage, default 90)
langlearn-tts synthesize "Привет" --voice tatyana --rate 70 -o privet.mp3

# Pair: English + German stitched with a pause
langlearn-tts synthesize-pair "good morning" "Guten Morgen" \
  --voice1 joanna --voice2 daniel -o pair.mp3

# Batch from JSON file (["hello", "world", "good morning"])
langlearn-tts synthesize-batch words.json -d output/

# Batch merged into single file
langlearn-tts synthesize-batch words.json -d output/ --merge --pause 800

# Pair batch from JSON file ([["strong", "stark"], ["house", "Haus"]])
langlearn-tts synthesize-pair-batch pairs.json -d output/

# Browse AI tutor prompts
langlearn-tts prompt list
langlearn-tts prompt show german-high-school | pbcopy

MCP Tools

All four tools are available in Claude Desktop once the server is configured:

Tool	Description
synthesize	Single text to MP3
synthesize_batch	Multiple texts, optionally merged
synthesize_pair	Two texts stitched with a pause
synthesize_pair_batch	Multiple pairs, optionally merged

Each tool accepts auto_play (default: true) to play audio immediately after synthesis.

Roadmap

ElevenLabs Backend

Highest voice quality. 29+ languages, 5,000+ voices, voice cloning. Setup: ELEVENLABS_API_KEY env var. Free tier: 10K chars/month.

Development

# Install with dev dependencies
uv sync --all-extras

# Run tests
uv run pytest tests/ -v

# Linting and formatting
uv run ruff check src/ tests/
uv run ruff format src/ tests/

# Type checking
uv run mypy src/ tests/
uv run pyright src/ tests/

License

MIT