Giggy MCP — text-to-speech and recorded transcription for AI agents

Giggy MCP is a remote Streamable HTTP Model Context Protocol (MCP) server for using Giggy text-to-speech and recorded-audio speech-to-text from coding agents and AI clients.

It provides Giggy speech tools to Codex, Claude Code, Cursor, VS Code, Cline, Windsurf-compatible clients, and other MCP clients.

MCP registry and plugin directories

Giggy's remote speech MCP endpoint is:

https://giggy.ai/mcp

This repository contains the publication artifacts for:

• Official MCP Registry: server.json

• OpenAI / Codex: openai-plugin/

• Claude Code: .claude-plugin/plugin.json

See directory submission status and requirements.

A public registry listing, plugin submission, and approved plugin publication are separate steps. Consult the submission document for verified status.

Related MCP server: kokoro-tts

Install for AI coding agents

Agent Skill — Codex and Claude Code

npx skills add giggy-ai/giggy-mcp --skill giggy-speech

The skill provides Giggy speech-generation and recorded-transcription instructions. An MCP connection is still required.

Claude Code plugin

claude plugin marketplace add giggy-ai/giggy-mcp
claude plugin install giggy-speech@giggy

Codex

Follow the existing Codex MCP setup below.

Example prompt

"Use Giggy to list available English voices, generate a short Batch speech sample saying 'Hello from Giggy', and return the completed audio URL."

Discover Giggy

• Official MCP Registry

• Speech API docs

• Runnable examples

• Directory submission status

Quick setup

Use Giggy MCP with Codex

Set GIGGY_API_KEY in your environment, then add to ~/.codex/config.toml:

[mcp_servers.giggy-speech]
url = "https://giggy.ai/mcp"
bearer_token_env_var = "GIGGY_API_KEY"

Use Giggy MCP with Claude Code

Set GIGGY_API_KEY, then configure:

{
  "mcpServers": {
    "giggy-speech": {
      "type": "http",
      "url": "https://giggy.ai/mcp",
      "headers": { "Authorization": "Bearer ${GIGGY_API_KEY}" }
    }
  }
}

Keep API keys out of configuration files committed to source control.

Remote MCP server

https://giggy.ai/mcp

Transport:

Streamable HTTP

The current Giggy MCP endpoint is stateless and accepts POST requests.

Authentication

Use a Giggy API key:

Authorization: Bearer $GIGGY_API_KEY

Giggy API keys begin with:

giggy_sk_

Keep the key in your MCP client's secret or environment configuration.

Do not:

• put it in ordinary prompts

• commit it to source control

• embed it in browser JavaScript

Speech tools

This repository documents these Giggy speech tools:

list_voices
list_my_voices
generate_speech
get_speech_generation
transcribe_audio

Read the connected server's tool schemas before calling these tools. Recorded transcription is asynchronous admission, followed by durable status/result retrieval. MCP does not transport live microphone frames; use the Python or Node.js SDK for that workflow.

Transcribe recorded audio with a coding assistant

Connect MCP with your own Giggy API key, then ask: "Use Giggy to transcribe my authorised recording with the available recorded-audio tool, retain the generation UUID, and retrieve the completed transcript."

The assistant must inspect transcribe_audio's current schema, prepare the supported input and use one idempotency key per intended operation. Poll get_speech_generation without resubmitting. Retrieve the canonical transcript only after completion; do not treat admission as final text. Check pricing and limits before paid usage. The current transcript contract does not provide speaker diarization, word timestamps, sentiment or PII redaction.

For SDKs, Pipecat, n8n and learning resources, use the developer tool guide.

Recommended speech workflow

1. Call list_voices or list_my_voices.

2. Select the exact returned voice_id.

3. Call generate_speech.

4. Supply a fresh idempotency_key for each new intended generation.

5. Save generation.generation_uuid.

6. Call get_speech_generation while the status is queued or processing.

7. When the status becomes completed, use generation.result.url.

Do not resubmit a new generation while polling an existing generation.

Use Giggy MCP with Codex

Set:

export GIGGY_API_KEY="giggy_sk_..."

Then add this to:

~/.codex/config.toml

[mcp_servers.giggy-speech]
url = "https://giggy.ai/mcp"
bearer_token_env_var = "GIGGY_API_KEY"

A ready-to-copy version is included at:

examples/codex-config.toml

Verify:

codex mcp list

Use Giggy MCP with Claude Code

Set:

export GIGGY_API_KEY="giggy_sk_..."

A project MCP configuration is included at:

examples/claude-code.mcp.json

Its contents are:

{
  "mcpServers": {
    "giggy-speech": {
      "type": "http",
      "url": "https://giggy.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${GIGGY_API_KEY}"
      }
    }
  }
}

Copy that configuration to:

.mcp.json

in the project where Claude Code should use Giggy.

Then run:

claude mcp list

or use:

/mcp

inside Claude Code.

Other MCP clients

Ready-to-copy client configurations are included for:

Cursor

Set:

export GIGGY_API_KEY="giggy_sk_..."

Copy or merge:

examples/cursor.mcp.json

into:

.cursor/mcp.json

for project configuration, or:

~/.cursor/mcp.json

for global configuration.

VS Code

Copy or merge:

examples/vscode.mcp.json

into:

.vscode/mcp.json

VS Code will prompt securely for the Giggy API key.

Cline

Open Cline's MCP server configuration and copy the contents of:

examples/cline.mcp.json

Replace:

YOUR_GIGGY_API_KEY

in your local configuration only.

Do not commit the configured file.

Windsurf-compatible clients

For installations that use:

~/.codeium/windsurf/mcp_config.json

merge the contents of:

examples/windsurf.mcp.json

and replace:

YOUR_GIGGY_API_KEY

in the local configuration only.

Raw MCP examples

Set:

export GIGGY_API_KEY="giggy_sk_..."

Initialize:

./examples/initialize.sh

List tools:

./examples/list-tools.sh

List public voices:

./examples/list-voices.sh

Important behavior

generate_speech returns durable generation metadata.

It does not return live MP3 or PCM audio bytes through MCP.

For progressive PCM audio, use:

POST https://giggy.ai/v1/text-to-speech

with:

mode=streaming
output_format=pcm_24000

Developer resources

Speech API documentation:

https://giggy.ai/docs/speech-api

OpenAPI:

https://giggy.ai/v1/openapi.json

Runnable examples:

https://github.com/giggy-ai/giggy-examples

Pricing:

https://giggy.ai/pricing

Official SDK and runnable examples:

• Giggy JavaScript/TypeScript SDK

• Giggy integration examples