mcpField
S
server

server

github.com/terrylicaCloud & DevOps171 installsUpdated 1d ago
Repository

About server

A skill for managing the Kokoro TTS HTTP server, which provides an OpenAI-compatible speech endpoint on localhost. It covers starting, stopping, and checking the server, along with its configuration and troubleshooting.

Key features

  1. 01Start and stop the HTTP server
  2. 02Expose health and model endpoints
  3. 03Synthesize speech in WAV, MP3, Opus, or PCM
  4. 04Configure host, port, voice, language, and speed
  5. 05Troubleshoot startup and model-loading issues

Use cases

  1. 01Run Kokoro TTS for local speech synthesis
  2. 02Check server health and available models
  3. 03Configure server behavior through environment variables

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/terrylica/cc-skills --skill server

After installing, type/serverin Claude Code to confirm it loaded.

Bundled filesreferences/server-api.mdreferences/service-management.md

Details

From the project README

Kokoro TTS Server

Manage the Kokoro TTS HTTP server — an OpenAI-compatible /v1/audio/speech endpoint on localhost:8779.

Self-Evolving Skill: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

Server Overview

The server provides:

  • GET /health — Health status JSON
  • GET /v1/models — List available models
  • POST /v1/audio/speech — Synthesize text to audio (WAV, MP3, Opus, PCM)

Quick Start

Start (foreground, for testing)
~/.local/share/kokoro/.venv/bin/python ~/.local/share/kokoro/tts_server.py
Start (launchd, for production)

Per the macOS launchd policy, the launchd plist must launch a compiled Swift binary (not a bash script). Guide the user through:

  1. Compile Swift launcher binary
  2. Create launchd plist at ~/Library/LaunchAgents/com.terryli.kokoro-tts-server.plist
  3. Bootstrap: launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.terryli.kokoro-tts-server.plist
Stop
launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/com.terryli.kokoro-tts-server.plist
Verify
curl -s http://127.0.0.1:8779/health | python3 -m json.tool

Expected: {"status": "ok", "provider": "kokoro-tts-mlx", "model": "mlx-community/Kokoro-82M-bf16", "device": "mlx-metal"}

Environment Variables

VariableDefaultPurpose
KOKORO_SERVER_PORT8779Listen port
KOKORO_SERVER_HOST127.0.0.1Bind address
KOKORO_DEFAULT_VOICEaf_heartDefault voice
KOKORO_DEFAULT_LANGen-usDefault language
KOKORO_DEFAULT_SPEED1.0Speech speed (0.1–5.0)
KOKORO_PLAY_LOCAL0Play via afplay

Troubleshooting

IssueCauseSolution
Port already in useAnother server runninglsof -i :8779 to find, kill it
Model load failsNot installedRun /kokoro-tts:install first
Slow first requestWarmup synthesisNormal — first request triggers model load

Post-Execution Reflection

After this skill completes, check before closing:

  1. Did the command succeed? — If not, fix the instruction or error table that caused the failure.
  2. Did parameters or output change? — If the underlying tool's interface drifted, update Usage examples and Parameters table to match.
  3. Was a workaround needed? — If you had to improvise (different flags, extra steps), update this SKILL.md so the next invocation doesn't need the same workaround.

Only update if the issue is real and reproducible — not speculative.

Comments

Markdown supported