MCP Server | Sarvam API Docs

Sarvam API MCP server

Official Sarvam Model Context Protocol (MCP) server. Exposes every public Sarvam API — STT (batch and realtime), TTS, text translation, transliteration, Language ID, LLM (105B and 105B Conversations), Document AI (parse, extract, classify, split), Document Translation, Dubbing, and Pronunciation Dictionaries — as first-class MCP tools so any MCP-aware client (Claude Desktop, Claude Code, Cursor, Windsurf, Zed) can call Sarvam with zero boilerplate.

For whole-file translation (PDF, Office, HTML), see the Document Translation API in the docs — the MCP server’s sarvam_tools_translate tool covers text translation only, while sarvam_tools_document_translate handles documents.

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

Quickstart

1. Get your API key

2. Add to your MCP client

Paste this JSON into your favorite agent (Cursor, Claude Desktop, Windsurf, etc.) and it’ll set up Sarvam for you:

{
  "mcpServers": {
    "sarvam": {
      "command": "uvx",
      "args": ["sarvam-mcp"],
      "env": {
        "SARVAM_API_KEY": "<YOUR_SARVAM_API_KEY>"
      }
    }
  }
}

Replace <YOUR_SARVAM_API_KEY> with your actual API key.

If you installed with pip install sarvam-mcp instead, drop the args array and use the console script directly:

{
  "mcpServers": {
    "sarvam": {
      "command": "sarvam-mcp",
      "env": {
        "SARVAM_API_KEY": "<YOUR_SARVAM_API_KEY>"
      }
    }
  }
}

3. Alternative: credentials file

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

api_key = <YOUR_SARVAM_API_KEY>

The server checks the SARVAM_API_KEY env var first, then falls back to ~/.sarvam/credentials.

Verify your install

Ask your assistant something that exercises a Sarvam tool, for example:

“Translate ‘good morning’ to Hindi using sarvam.”

Tools

All defaults below reflect the latest non-deprecated models. Tools are registered under their namespace prefix, so the name your client sees is exactly what’s in the tables below.

Speech-to-text

Tool	What it does	Default model
`sarvam_tools_stt_transcribe`	Audio file → transcript. Five modes: `transcribe`, `translate` (any Indic language → English), `verbatim`, `translit`, `codemix`	`saaras:v4`
`sarvam_tools_stt_realtime`	Mono 16-bit WAV (8000 or 16000 Hz) → realtime transcript over the WebSocket	`saaras:v3-realtime`
`sarvam_tools_stt_batch_submit`	Long audio (> 30 s) → batch job; creates the job and uploads the audio for you	—
`sarvam_tools_stt_batch_status`	Poll a batch job, returns the transcript when completed	—
`sarvam_tools_stt_batch_download`	Fresh presigned download URLs for a finished batch job	—

See Batch Speech-to-Text for the underlying job pipeline.

Text-to-speech

Tool	What it does	Default model
`sarvam_tools_tts_speak`	Text → audio file, written under `SARVAM_MCP_BASE_PATH`	`bulbul:v3` (default) or `bulbul:v4-flash`
`sarvam_tools_tts_stream`	Text → streamed audio over the TTS WebSocket	`bulbul:v3` (default) or `bulbul:v4-flash`

Speakers are model-specific: bulbul:v3 uses short names (shubh is the default), while bulbul:v4-flash uses persona IDs of the form <voice>_<lang>_<style> (default shubh_enhi_ads). See Voices for both catalogs.

Text and language

Tool	What it does	Default model
`sarvam_tools_translate`	Cross-language text translation	`mayura:v1` (11 languages, formal/colloquial/code-mixed) or `sarvam-translate:v1` (22 scheduled languages + English, formal only)
`sarvam_tools_transliterate`	Script conversion without translating meaning	—
`sarvam_tools_identify_language`	Detect language (BCP-47) and script	—
`sarvam_tools_llm_complete`	Chat completions, OpenAI-compatible message format incl. function calling and structured output	`sarvam-105b` (128K context) or `sarvam-105b-conversations` (32K, post-trained for dialogue)

Document AI

Tool	What it does	Default model
`sarvam_tools_vision_parse`	Full-document OCR that keeps layout, reading order and tables → markdown (`md`), HTML, or JSON. Pass `md`, not `markdown`	Sarvam Vision
`sarvam_tools_vision_extract`	Schema extraction — pass a JSON schema, get structured values back	Sarvam Vision
`sarvam_tools_vision_classify`	Label the whole document, or each page with `scope='page'`, against your categories	Sarvam Vision
`sarvam_tools_vision_split`	Split a bundle of pages into separate child documents (`semantic`, `fixed_pages`, `page_ranges`, or `triggers`)	Sarvam Vision
`sarvam_tools_vision_job_status`	Poll any Document AI job — parse, extract, classify or split	—

parse replaces the old digitise job, which was renamed upstream. See Document Intelligence for job shapes.

Page limits: 30 pages per PDF for parse, 20 for extract, and 500 for split and classify. Split and Classify also accept up to 10 documents per request, 20 categories and 1,000 segments. Full table in Languages, Formats & Limits.

Document translation and dubbing

Tool	What it does	Default model
`sarvam_tools_document_translate`	Whole document (PDF, Word, Excel, PowerPoint, HTML) with layout preserved, up to 12 target languages	—
`sarvam_tools_document_translate_status`	Poll a document translation job; set `export=true` once a language is completed to get download links	—
`sarvam_tools_dubbing_submit`	Start an official dubbing job for a video or audio file — creates the job, uploads the media, starts processing	—
`sarvam_tools_dubbing_status`	Poll a dubbing job, or fetch signed export URLs (video, audio, mp3, srt) that last about 24 hours	—

See Dubbing API for pipeline and export formats.

Pronunciation dictionaries

Tool	What it does	Default model
`sarvam_tools_pronunciation_list`	List pronunciation dictionary IDs you own	—
`sarvam_tools_pronunciation_get`	Get a dictionary’s word → pronunciation entries	—
`sarvam_tools_pronunciation_create`	Create a dictionary to control how specific words are spoken in TTS	—
`sarvam_tools_pronunciation_delete`	Delete a dictionary by ID	—

Multi-step workflows

Tool	What it does	Default model
`sarvam_tools_voice`	Voice agent loop: transcribe an Indic audio file → LLM reply → synthesize the reply	—
`sarvam_tools_dub`	Dub a short Indic audio clip into another Indic language (STT → translate → TTS)	—
`sarvam_tools_localize`	Translate a JSON or `key=value` string-table file, walking every string value (nested JSON supported)	—
`sarvam_tools_recall`	Answer a natural-language question grounded in a set of files — audio is transcribed, text and markdown read directly	—

sarvam_tools_text_analytics is still registered for compatibility but raises immediately: Sarvam retired the /text-analytics endpoint, so there is no network call to make. For document and text extraction, use the Document AI tools above.

Builder tools

Builder tools help your assistant write code that uses Sarvam. They don’t call the API.

Tool	What it does
`sarvam_code_api_reference`	Authoritative request/response shape for an endpoint — parameters, defaults, errors
`sarvam_code_languages`	Supported BCP-47 language codes for a given API (coverage varies by endpoint)
`sarvam_code_speakers`	TTS speakers compatible with a model tag, e.g. `bulbul:v4-flash`
`sarvam_code_pricing`	Current pricing and billing unit for a model
`sarvam_code_snippet`	Tested, copy-paste-ready code snippet for calling a Sarvam API
`sarvam_code_recommend_model`	Recommend the right model and mode from a plain-English description of what you’re building
`sarvam_code_validate_request`	Validate a draft request body against the canonical schema before you send it

Configuration

Env var	Default	Description
`SARVAM_API_KEY`	—	Required. API key from indus.sarvam.ai. Falls back to `~/.sarvam/credentials`.
`SARVAM_API_BASE_URL`	`https://api.sarvam.ai`	Override for testing/staging.
`SARVAM_MCP_BASE_PATH`	`~/Desktop`	Where audio/document files land.
`SARVAM_AUDIO_OUTPUT_MODE`	`files`	`files`, `resources`, or `both` — whether audio comes back as a file path, an MCP resource, or both.

Two namespaces

The server exposes tools across two namespaces:

sarvam_tools_*, runtime tools. Call Sarvam APIs to do things (transcribe, speak, translate, parse a document, etc.).
sarvam_code_*, builder tools. Help you write code that uses Sarvam: docs, endpoint shapes, language lists, code snippets, starter projects.