Skip to main content
Glama
fgasparetto

Voice Transcriber MCP Server

by fgasparetto
OverviewSchemaRelated ServersScoreDiscussions
Python
Hybrid

Voice Transcriber MCP Server

MCP server that automatically transcribes Google Chat voice messages using Groq Whisper API (whisper-large-v3). No local GPU needed.

When Claude Code encounters an audio attachment in a Google Chat message, this server transcribes it immediately without asking for confirmation.

Features

  • Transcribe Google Chat voice messages by URL (automatic)

  • Transcribe local audio files (mp3, m4a, wav, ogg, flac, webm, aac)

  • Uses Groq Whisper API (free tier, fast, cloud-based)

  • Reuses Google Chat OAuth2 credentials (no separate Google auth needed)

Related MCP server: vibevoice-asr

Prerequisites

1. Groq API Key (free)

  1. Go to console.groq.com/keys

  2. Create a free account

  3. Generate an API key

  4. You'll set this as GROQ_API_KEY in your MCP config (see below)

2. Google Chat OAuth2 Token

This server needs a valid Google Chat OAuth2 token (token.json) to fetch messages and download audio attachments.

If you already use a Google Chat MCP server (e.g. multi-chat-mcp-server), the token is already available. Default path:

~/tools/multi-chat-mcp-server/src/providers/google_chat/token.json

If your token is in a different location, set the GCHAT_TOKEN_PATH environment variable.

If you don't have a Google Chat token yet, you need to:

  1. Create a Google Cloud project with Chat API enabled

  2. Create OAuth2 credentials (Desktop app)

  3. Run the OAuth flow to generate token.json with scopes:

    • https://www.googleapis.com/auth/chat.messages.readonly

    • https://www.googleapis.com/auth/chat.spaces.readonly

3. uv (Python package manager)

OS

Command

Linux / macOS / WSL

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Verify: uv --version

Installation

git clone https://github.com/fgasparetto/voice-transcriber-mcp.git
cd voice-transcriber-mcp
uv sync

Configuration

Add to your Claude Code MCP config (.mcp.json or ~/.claude.json):

{
  "mcpServers": {
    "voice-transcriber": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "--directory", "/path/to/voice-transcriber-mcp",
        "run", "python", "server.py"
      ],
      "env": {
        "GROQ_API_KEY": "gsk_your_groq_api_key_here"
      }
    }
  }
}

Replace:

  • /path/to/voice-transcriber-mcp with the actual clone directory

  • gsk_your_groq_api_key_here with your Groq API key

Environment Variables

Variable

Required

Default

Description

GROQ_API_KEY

Yes

—

Groq API key (get one free)

GCHAT_TOKEN_PATH

No

~/tools/multi-chat-mcp-server/src/providers/google_chat/token.json

Path to Google Chat OAuth2 token

Tools

transcribe_voice_message

Transcribe a voice message from Google Chat. Called automatically by Claude when it encounters an audio attachment.

transcribe_voice_message(
  message_url="https://chat.google.com/dm/SPACE/THREAD/MSG",
  language="it"
)

transcribe_audio_file

Transcribe a local audio file.

transcribe_audio_file(
  file_path="/tmp/recording.m4a",
  language="it"
)

Platform Notes

Linux

No additional steps. Ensure uv is in your PATH.

macOS

  • If uv not found after install: export PATH="$HOME/.local/bin:$PATH"

Windows (WSL)

Claude Code runs inside WSL. All paths must be Linux-style:

  • Token path: /home/USER/tools/... (NOT /mnt/c/...)

  • If uv not found: source ~/.bashrc or add ~/.local/bin to PATH

Troubleshooting

Problem

Solution

GROQ_API_KEY not set

Add it to the env section in your MCP config

Google Chat token not found

Set GCHAT_TOKEN_PATH or authenticate your Google Chat MCP

Groq API error 413

Audio file too large (Groq limit: 25MB)

uv: command not found

Install uv (see Prerequisites)

How It Works

Claude Code → MCP tool call → server.py
  1. Parse Google Chat URL
  2. Fetch message via Google Chat API (OAuth2 token)
  3. Download audio attachment via media API
  4. Send to Groq Whisper API (whisper-large-v3)
  5. Return transcribed text

License

MIT

Available Tools

2 tools
transcribe_audio_fileB

Transcribe a local audio file using Groq Whisper API (whisper-large-v3).

Use this tool to transcribe any local audio file (mp3, m4a, wav, ogg, flac, etc.).

Args: file_path: Absolute path to the audio file language: Language code for transcription (default: "it" for Italian)

Returns: The transcribed text

ParametersJSON Schema
NameRequiredDescriptionDefault
file_pathYes
languageNoit

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must fully disclose behaviors. It mentions the API and model, but omits important details such as file size/duration limits, cost implications, whether the file is uploaded, or any side effects. This lack of transparency is a significant gap for a tool that likely involves network calls and data processing.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise (4 sentences) and well-structured with separate sections for arguments and returns. It avoids unnecessary details but includes a helpful list of supported file types. The use of bullet points and clear headers enhances readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity and the presence of an output schema (which indicates structured return), the description adequately covers the core functionality and parameters. However, it lacks details on error handling, pagination, or additional response fields, leaving gaps for an agent to know what to expect in edge cases.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 0% description coverage, so the description compensates by explaining each parameter's purpose and the default language. However, it does not specify allowed language codes or file path format, leaving some ambiguity.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb (transcribe), the resource (local audio file), and the specific model (Groq Whisper API whisper-large-v3). It explicitly lists supported file types and distinguishes from sending a voice message by emphasizing local files.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description specifies to use for local audio file transcription, but does not provide guidance on when not to use it or when to choose the sibling tool 'transcribe_voice_message' instead. The context implies local files, but lacks explicit exclusions or alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

transcribe_voice_messageA

Transcribe a voice message from Google Chat.

IMPORTANT: Call this tool AUTOMATICALLY whenever you see a Google Chat message with an audio attachment (contentType: audio/*). Do NOT ask the user first - just transcribe. Treat voice messages like text: transcribe immediately and show the result.

Args: message_url: Google Chat message URL or resource name (spaces/X/messages/Y) Example URLs: - https://chat.google.com/dm/SPACE/THREAD/MSG?cls=10 - spaces/SPACE_ID/messages/MSG_ID language: Language code for transcription (default: "it" for Italian)

Returns: The transcribed text of the voice message

ParametersJSON Schema
NameRequiredDescriptionDefault
message_urlYes
languageNoit

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden for behavioral disclosure. However, it only mentions the basic operation and does not disclose authentication, rate limits, side effects, or error handling. The instruction to transcribe immediately adds minimal context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with an 'IMPORTANT' section and 'Args' section, but is slightly verbose. It effectively communicates key points without excessive detail. Minor redundancy in the 'Returns' line could be removed.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the presence of an output schema (not shown but referenced), the description covers the essential context: when to use, parameter details, and return value description. It lacks error handling or timeout information, but for a simple transcription tool, it is mostly complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema coverage is 0%, but the description compensates by explaining the 'message_url' parameter with example formats (URLs and resource names) and gives the default language and its value ('it' for Italian). This adds meaningful semantics not present in the raw schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Transcribe a voice message from Google Chat', specifying both the action and the resource. It distinguishes from the sibling tool 'transcribe_audio_file' by focusing on Google Chat messages.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The 'IMPORTANT' section explicitly instructs the AI to call this tool automatically when a Google Chat message with an audio attachment is detected, without asking the user. This provides clear when-to-use guidance and contrasts with the sibling tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.9/5.0
Disambiguation5/5

The two tools target distinct input sources: one for local audio files and one for Google Chat voice messages. Their purposes are clearly separated, leaving no ambiguity for an agent.

Naming Consistency5/5

Both tool names follow the identical pattern 'transcribe_<source>', using snake_case and a clear verb-noun structure. Naming is consistent and predictable.

Tool Count4/5

With only 2 tools, the set is minimal but matches the narrow scope of transcribing voice from two specific sources. It is slightly underpopulated but not unreasonable.

Completeness4/5

The server covers the core need of transcribing audio from local files and Google Chat messages. Minor gaps exist, such as no support for URLs or other chat platforms, but it is complete for its focused purpose.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/fgasparetto/voice-transcriber-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server