Giggy Speech MCP README

Giggy MCP — text-to-speech for AI agents

Giggy MCP is a remote Streamable HTTP Model Context Protocol (MCP) server for using Giggy text-to-speech 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.

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 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

The MCP server may expose other Giggy tools outside the speech scope of this repository.

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