gnani-mcp

Official Gnani AI MCP server. Exposes Gnani Speech-to-Text (Prisma v2.5 / v3.0), Text-to-Speech (Timbre v2.5 / v3.0), and Voice Clone APIs as first-class MCP tools, so any MCP-aware client (Claude Desktop, Claude Code, Cursor, Windsurf, Zed) can call them with zero boilerplate.

Cross-platform Python package: macOS, Windows, and Linux (Python 3.10+).

Quickstart

1. Get your API key

Sign up or log in at app.gnani.ai and copy your API key.

2. Add to your MCP client

Paste this into your MCP config JSON:

{
  "mcpServers": {
    "gnani": {
      "command": "uvx",
      "args": ["gnani-mcp"],
      "env": {
        "GNANI_API_KEY": "your-api-key"
      }
    }
  }
}

Replace your-api-key with your actual API key.

If you have installed via pip install gnani-mcp, use the console script directly:

{
  "mcpServers": {
    "gnani": {
      "command": "gnani-mcp",
      "env": {
        "GNANI_API_KEY": "your-api-key"
      }
    }
  }
}

3. Config file locations

Zed uses a different key (context_servers) than the JSON above:

{
  "context_servers": {
    "gnani": {
      "command": "uvx",
      "args": ["gnani-mcp"],
      "env": {
        "GNANI_API_KEY": "your-api-key"
      }
    }
  }
}

Alternative: credentials file

Instead of setting GNANI_API_KEY in the JSON config, you can store it in ~/.gnani/credentials:

api_key = your-api-key

The server checks GNANI_API_KEY env var first, then falls back to ~/.gnani/credentials.

Install

# Option A: run directly (no install needed)
uvx gnani-mcp

# Option B: install globally
pip install gnani-mcp

Tools

Choosing a model

Both new models are opt-in — omit model and behaviour is unchanged (Prisma v2.5 / Timbre v2.5).

Prisma v3.0 (model="prisma-v3.0") on gnani_stt_transcribe and gnani_stt_batch_transcribe:

• language_code="indic-auto" lets the model identify the language, or pass 1–4 comma-separated codes ("hi-IN,en-IN") as hints. REST results include detected_language_code.
• format adds codemix (English words stay Latin) and, on REST only, transliterate (Latin-letter output). When format is omitted v3.0 picks a style per request (digits for a single hi-IN/en-IN) — pass format explicitly to keep v2.5-style output.
• Context hints: keyterms, topic, speaker_names, and (REST only) previous_text. On Batch only one of keyterms, topic, topic + keyterms, or speaker_names is accepted, and topic must be 30–1,600 characters.

Timbre v3.0 (model="timbre-v3.0") on gnani_tts_synthesize:

• Voices are not shared between models: Shivani, Lakshmi, Kalpana, Chetana, Vasudha, Riyaa, Tarika (F); Avinash, Shubham, Prakash, Devansh, Yashraj, Harshad (M). Every voice speaks all 10 languages.
• Inline audio tags in text: <laugh>, <giggle>, <sigh>, <exhales>, <sniffles>, <yawns>, <coughs>, <clears throat>, <whispers>, <shouting>, <excited>, <slow>, <pauses> (silence, never spoken). A tag applies until the next tag; tags are billed as characters. With v2.5 they are stripped, and the tool returns a warning.

Configuration

Running over HTTP

By default the server speaks MCP over stdio. To serve it over HTTP instead:

gnani-mcp --transport http --host 127.0.0.1 --port 8000 --path /mcp

--transport accepts stdio (default), http, sse, or streamable-http.

Supported Languages

STT (Prisma v2.5 / v3.0)

TTS (Timbre v2.5 / v3.0) — also supports Hinglish (hi-en) and auto

Timbre v2.5: 42 voices across all 10 Indian languages plus Hinglish, one preferred language each. Timbre v3.0: 13 voices that each speak all 10 languages. Use gnani_tts_list_voices (with model) to browse.

Voice Clone Workflow

# Step 1 — generate embedding from reference audio (do this once per voice)
embedding_result = gnani_vc_generate_embedding(audio_path="/path/to/reference.wav")
speaker_embedding = embedding_result["speaker_embedding"]

# Step 2 — synthesize with the cloned voice (reuse embedding as many times as needed)
audio_result = gnani_vc_synthesize(
    text="नमस्ते, आप कैसे हैं?",
    speaker_embedding=speaker_embedding,
)
print(audio_result["audio_file"])  # path to saved WAV file

Print client config

gnani-mcp --print
gnani-mcp --api-key=your-key --print

This prints the MCP client config JSON for your machine (using uvx if it's installed).

License

MIT