Gladia MCP

Speech-to-text for AI assistants. @gladiaio/mcp is an open-source Model Context Protocol server that connects hosts like Cursor, Claude, and Codex to your Gladia account.

Create pre-recorded transcription jobs and manage both pre-recorded and live jobs — with speaker diarization, translation, subtitles, summaries, sentiment analysis, named-entity recognition, PII redaction, and custom vocabulary. Live tools are metadata-only (get / list / delete); this server does not start or stream live audio.

Creating a transcription is billable to the account behind your GLADIA_API_KEY. The server returns a job ID immediately; Gladia finishes the work asynchronously.

Start here: Install · Quick start · Try it · Features · MCP interface · Docs & links

Install

You need:

Node.js 22.18+ (22 and 24 are tested)
A Gladia API key from app.gladia.io
An MCP-compatible host (Cursor, Claude Desktop, Claude Code, Codex, …)

The published package is @gladiaio/mcp. Hosts typically launch it with npx — no global install required.

Quick start

Cursor

Add this to .cursor/mcp.json (project) or your Cursor MCP settings:

{
  "mcpServers": {
    "gladia": {
      "command": "npx",
      "args": ["-y", "@gladiaio/mcp"],
      "env": {
        "GLADIA_API_KEY": "your-api-key"
      }
    }
  }
}

Claude Code

claude mcp add gladia --env GLADIA_API_KEY=your-api-key -- npx -y @gladiaio/mcp

Claude Desktop

Use the same JSON shape as Cursor in Claude Desktop’s MCP config, then restart the app.

Codex

codex mcp add gladia --env GLADIA_API_KEY=your-api-key -- npx -y @gladiaio/mcp

This configures the server for the Codex CLI, IDE extension, and ChatGPT desktop app (they share MCP config).

Restart your host after changing config. Never commit your API key or pass it as a tool argument.

Try it

Once connected, ask your assistant something like:

Transcribe https://example.com/interview.mp3 with speaker diarization and a bullet-point summary.

Typical pre-recorded flow:

transcribe_pre_recorded creates a job and returns its ID right away.
get_pre_recorded_transcription polls until status is done or error.
The completed response includes the transcript and any requested add-ons.
list_pre_recorded_transcriptions browses jobs (filters + pagination).
delete_pre_recorded_transcription permanently removes a remote job when you are done.

For live sessions started outside MCP (SDK, CLI, or another app), use get_live_transcription, list_live_transcriptions, and delete_live_transcription. Pre-recorded and live IDs are separate namespaces — always use the matching tool family.

Built-in prompts:

“Use transcribe_with_diarization for this recording.”
“Use transcribe_and_translate to translate this recording into French.”
“Use explain_transcription_result for job <job-id>.”

Features

Capability	Support
Pre-recorded transcription	Yes
Live get / list / delete	Yes
Live create / streaming	No
Language hints and switching	Yes
Speaker diarization	Yes
Translation	Yes
SRT and VTT subtitles	Yes
Summarization	Yes
Sentiment analysis	Yes
Named-entity recognition	Yes
PII redaction	Yes
Custom vocabulary	Yes
Trusted local-file uploads	Desktop default

Options for transcribe_pre_recorded use the same nested field names as Gladia’s pre-recorded API. Example:

{
  "audio_url": "https://example.com/interview.mp3",
  "language_config": {
    "languages": ["en"]
  },
  "diarization": true,
  "translation": true,
  "translation_config": {
    "target_languages": ["fr"]
  },
  "summarization": true,
  "summarization_config": {
    "type": "bullet_points"
  }
}

The MCP process does not download remote media. Public HTTPS URLs are passed to Gladia through the official @gladiaio/sdk.

Local files

upload_audio can read files from disk, but only inside trusted roots. When GLADIA_LOCAL_FILE_ROOTS is unset, that root is your Desktop. Paths (absolute or relative) must resolve inside that directory — or inside roots you configure. Paths outside are rejected.

GLADIA_LOCAL_FILE_ROOTS=/absolute/path/to/audio npx -y @gladiaio/mcp

Separate multiple roots with : on macOS/Linux or ; on Windows. Set GLADIA_LOCAL_FILE_ROOTS to an empty value to disable local uploads.

After a successful upload, pass the returned audio_url to transcribe_pre_recorded.

Safety checks: symlink resolution before root checks, regular files only, max 1,000,000,000 bytes. Only point roots at directories you trust the host to upload.

MCP interface

Tools

Tool	What it does
`delete_live_transcription`	Permanently deletes an existing live session and its data.
`delete_pre_recorded_transcription`	Permanently deletes a pre-recorded job and its data.
`get_live_transcription`	Gets an existing live session’s status and available result.
`get_pre_recorded_transcription`	Gets a pre-recorded job’s current status and available result.
`list_live_transcriptions`	Lists existing live sessions with optional filters and pagination.
`list_pre_recorded_transcriptions`	Lists pre-recorded jobs with optional filters and pagination.
`transcribe_pre_recorded`	Starts an asynchronous, billable pre-recorded job.
`upload_audio`	Uploads a file from an allowed root (Desktop by default).

Breaking rename: get_transcription, list_transcriptions, and delete_transcription are now get_pre_recorded_transcription, list_pre_recorded_transcriptions, and delete_pre_recorded_transcription.

Resources

gladia://pre-recorded/{id} — status and result for a pre-recorded job
gladia://live/{id} — status and result for an existing live session
gladia://docs/feature-matrix — supported and deferred capabilities
gladia://docs/pre-recorded-limits — concurrency, duration/size/channels, formats
gladia://docs/sdk-policy — SDK, billing, and local-file safety policy

Prompts

explain_transcription_result
transcribe_and_translate
transcribe_with_diarization

All tools publish input/output schemas, structured results, and a JSON text fallback for hosts that do not consume structured content.

Configuration

Variable	Required	Purpose
`GLADIA_API_KEY`	Yes	Authenticates your Gladia account.
`GLADIA_API_URL`	No	Overrides the SDK API URL for a trusted proxy or test server.
`GLADIA_LOCAL_FILE_ROOTS`	No	Trusted directories for local uploads. Defaults to Desktop when unset; empty disables uploads.

Stdio transport only; one Gladia account per process. Diagnostics go to stderr so stdout stays the MCP channel. User-visible errors are sanitized (no credentials, headers, or transcript payloads in messages).

Current scope

This release is intentionally small and stateless: pre-recorded create/get/list/delete and live get/list/delete via the official SDK. It does not support live session create/streaming, callbacks, audio-to-LLM, custom spelling, or a hosted HTTP/OAuth transport.

Development

git clone https://github.com/gladiaio/gladia-mcp.git
cd gladia-mcp
npm ci
npm test

Use Node 22 or 24. Before opening a PR, run:

npm run check

That covers formatting, lint, TypeScript, coverage (≥90%), build, a real stdio handshake, and package checks. Prefer test-first changes with injected PreRecordedClient / LiveClient mocks — not real credentials or mocked network calls.

Optional integration test

Creates a billable job and deletes it in finally. Not part of PR CI:

GLADIA_API_KEY=your-api-key \
GLADIA_TEST_AUDIO_URL=https://example.com/audio.mp3 \
npm run test:integration

Inspect a local build with the MCP Inspector:

npm run build
GLADIA_API_KEY=your-api-key npx @modelcontextprotocol/inspector node dist/index.js

Releasing to npm

Maintainer-only via GitHub Actions Publish:

Ensure NPM_TOKEN can publish @gladiaio/mcp.
Run Publish with a SemVer (e.g. 0.1.1 or v0.1.1).
Review and merge the automated release/vX.Y.Z PR.
That merge automatically creates tag vX.Y.Z and runs npm publish --access public --provenance.

Do not publish from a laptop.

Docs & links

Resource	Link
Gladia product	gladia.io
API documentation	docs.gladia.io
Pre-recorded quickstart	docs.gladia.io/chapters/pre-recorded-stt/quickstart
Get an API key	app.gladia.io
npm package	@gladiaio/mcp
JavaScript SDK	@gladiaio/sdk
Terminal CLI	gladiaio/gladia-cli
Model Context Protocol	modelcontextprotocol.io
Issues & feature requests	github.com/gladiaio/gladia-mcp/issues

License

MIT © Gladia

Name		Name	Last commit message	Last commit date
.github		.github
docs/assets		docs/assets
src		src
tests		tests
.gitignore		.gitignore
.prettierignore		.prettierignore
AGENTS.md		AGENTS.md
LICENSE		LICENSE
README.md		README.md
commitlint.config.mjs		commitlint.config.mjs
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
tsdown.config.ts		tsdown.config.ts
vitest.config.ts		vitest.config.ts
vitest.integration.config.ts		vitest.integration.config.ts
vitest.stdio.config.ts		vitest.stdio.config.ts

Navigation Menu

Repository files navigation

Gladia MCP

Install

Quick start

Cursor

Claude Code

Claude Desktop

Codex

Try it

Features

Local files

MCP interface

Tools

Resources

Prompts

Configuration

Current scope

Development

Optional integration test

Releasing to npm

Docs & links

License

About

Releases

Used by

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Gladia MCP

Install

Quick start

Cursor

Claude Code

Claude Desktop

Codex

Try it

Features

Local files

MCP interface

Tools

Resources

Prompts

Configuration

Current scope

Development

Optional integration test

Releasing to npm

Docs & links

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Used by

Contributors

Languages