Skip to main content
Glama
deenesjakoruzh
arcaputo3

MCP Server Whisper

by arcaputo3
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

MCP Server Whisper

A Model Context Protocol (MCP) server for advanced audio transcription and processing using OpenAI's Whisper and GPT-4o models.

PyPI version License: MIT Python 3.10+ CI Status Built with uv

WARNING

This project has moved. Active development has migrated to TJC-LP/sanzaru. This repository is no longer maintained and will be archived. Please update your dependencies and issues to the new repo.

Overview

MCP Server Whisper provides a standardized way to process audio files through OpenAI's latest transcription and speech services. By implementing the Model Context Protocol, it enables AI assistants like Claude to seamlessly interact with audio processing capabilities.

Key features:

  • 🔍 Advanced file searching with regex patterns, file metadata filtering, and sorting capabilities

  • ⚡ MCP-native parallel processing - call multiple tools simultaneously

  • 🔄 Format conversion between supported audio types

  • 📦 Automatic compression for oversized files

  • 🎯 Multi-model transcription with support for all OpenAI audio models

  • 🗣️ Interactive audio chat with GPT-4o audio models

  • ✏️ Enhanced transcription with specialized prompts and timestamp support

  • 🎙️ Text-to-speech generation with customizable voices, instructions, and speed

  • 📊 Comprehensive metadata including duration, file size, and format support

  • 🚀 High-performance caching for repeated operations

  • 🔒 Type-safe responses with Pydantic models for all tool outputs

Note: This project is unofficial and not affiliated with, endorsed by, or sponsored by OpenAI. It provides a Model Context Protocol interface to OpenAI's publicly available APIs.

Related MCP server: MusicGPT MCP Server

Installation

# Clone the repository
git clone https://github.com/arcaputo3/mcp-server-whisper.git
cd mcp-server-whisper

# Using uv 
uv sync

# Set up pre-commit hooks
uv run pre-commit install

Environment Setup

Create a .env file based on the provided .env.example:

cp .env.example .env

Edit .env with your actual values:

OPENAI_API_KEY=your_openai_api_key
AUDIO_FILES_PATH=/path/to/your/audio/files

Note: Environment variables must be available at runtime. For local development with Claude, use a tool like dotenv-cli to load them (see Usage section below).

Usage

Local Development with Claude

The project includes a .mcp.json configuration file for local development with Claude. To use it:

  1. Ensure your .env file is configured with the required environment variables

  2. Launch Claude with environment variables loaded:

bunx dotenv-cli -- claude

This will:

  • Load environment variables from your .env file

  • Launch Claude with the MCP server configured per .mcp.json

  • Enable hot-reloading during development

The .mcp.json configuration:

{
  "mcpServers": {
    "whisper": {
      "command": "uv",
      "args": ["run", "mcp-server-whisper"],
      "env": {
        "OPENAI_API_KEY": "${OPENAI_API_KEY}",
        "AUDIO_FILES_PATH": "${AUDIO_FILES_PATH}"
      }
    }
  }
}

Exposed MCP Tools

Audio File Management

  • list_audio_files - Lists audio files with comprehensive filtering and sorting options:

    • Filter by regex pattern matching on filenames

    • Filter by file size, duration, modification time, or format

    • Sort by name, size, duration, modification time, or format

    • Returns type-safe FilePathSupportParams with full metadata

  • get_latest_audio - Gets the most recently modified audio file with model support info

Audio Processing

  • convert_audio - Converts audio files to supported formats (mp3 or wav)

    • Returns AudioProcessingResult with output path

  • compress_audio - Compresses audio files that exceed size limits

    • Returns AudioProcessingResult with output path

Transcription

  • transcribe_audio - Advanced transcription using OpenAI's models:

    • Supports whisper-1, gpt-4o-transcribe, and gpt-4o-mini-transcribe

    • Custom prompts for guided transcription

    • Optional timestamp granularities for word and segment-level timing

    • JSON response format option

    • Returns TranscriptionResult with text, usage data, and optional timestamps

  • chat_with_audio - Interactive audio analysis using GPT-4o audio models:

    • Supports gpt-4o-audio-preview (recommended) and dated versions

    • Note: gpt-4o-mini-audio-preview has limitations with audio chat and is not recommended

    • Custom system and user prompts

    • Provides conversational responses to audio content

    • Returns ChatResult with response text

  • transcribe_with_enhancement - Enhanced transcription with specialized templates:

    • detailed - Includes tone, emotion, and background details

    • storytelling - Transforms the transcript into a narrative form

    • professional - Creates formal, business-appropriate transcriptions

    • analytical - Adds analysis of speech patterns and key points

    • Returns TranscriptionResult with enhanced output

Text-to-Speech

  • create_audio - Generate text-to-speech audio using OpenAI's TTS API:

    • Supports gpt-4o-mini-tts (preferred) and other speech models

    • Multiple voice options (alloy, ash, ballad, coral, echo, sage, shimmer, verse, marin, cedar)

    • Speed adjustment and custom instructions

    • Customizable output file paths

    • Handles texts of any length by automatically splitting and joining audio segments

    • Returns TTSResult with output path

Supported Audio Formats

Model

Supported Formats

Transcribe

flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, webm

Chat

mp3, wav

Note: Files larger than 25MB are automatically compressed to meet API limits.

Example Usage with Claude

Claude, please transcribe my latest audio file with detailed insights.

Claude will automatically:

  1. Find the latest audio file using get_latest_audio

  2. Determine the appropriate transcription method

  3. Process the file with transcribe_with_enhancement using the "detailed" template

  4. Return the enhanced transcription

Claude, list all my audio files that are longer than 5 minutes and were created after January 1st, 2024, sorted by size.

Claude will:

  1. Convert the date to a timestamp

  2. Use list_audio_files with appropriate filters:

    • min_duration_seconds: 300 (5 minutes)

    • min_modified_time: <timestamp for Jan 1, 2024>

    • sort_by: "size"

  3. Return a sorted list of matching audio files with comprehensive metadata

Claude, find all MP3 files with "interview" in the filename and create professional transcripts for each one.

Claude will:

  1. Search for files using list_audio_files with pattern and format filters

  2. Make multiple parallel transcribe_with_enhancement tool calls (MCP handles parallelism natively)

  3. Each call uses enhancement_type: "professional" and returns a typed TranscriptionResult

  4. Return all transcriptions with full metadata in a well-formatted output

Claude, create audio with this script: "Welcome to our podcast! Today we'll be discussing artificial intelligence trends in 2025." Use the shimmer voice.

Claude will:

  1. Use the create_audio tool with:

    • text_prompt containing the script

    • voice: "shimmer"

    • model: "gpt-4o-mini-tts" (default high-quality model)

    • instructions: "Speak in an enthusiastic, podcast host style" (optional)

    • speed: 1.0 (default, can be adjusted)

  2. Generate the audio file and save it to the configured audio directory

  3. Provide the path to the generated audio file

Configuration with Claude Desktop

For production use with Claude Desktop (as opposed to local development), add this to your claude_desktop_config.json:

UVX

{
  "mcpServers": {
    "whisper": {
      "command": "uvx",
      "args": ["mcp-server-whisper"],
      "env": {
        "OPENAI_API_KEY": "your_openai_api_key",
        "AUDIO_FILES_PATH": "/path/to/your/audio/files"
      }
    }
  }
}

Recommendation (Mac OS Only)

  • Install Screen Recorder By Omi (free)

  • Set AUDIO_FILES_PATH to /Users/<user>/Movies/Omi Screen Recorder and replace <user> with your username

  • As you record audio with the app, you can transcribe multiple files in parallel with Claude

Development

This project uses modern Python development tools including uv, pytest, ruff, and mypy.

# Run tests
uv run pytest

# Run with coverage
uv run pytest --cov=src

# Format code
uv run ruff format src

# Lint code
uv run ruff check src

# Run type checking (strict mode)
uv run mypy --strict src

# Run the pre-commit hooks
pre-commit run --all-files

CI/CD Workflow

The project uses GitHub Actions for CI/CD:

  1. Lint & Type Check: Ensures code quality with ruff and strict mypy type checking

  2. Tests: Runs tests on multiple Python versions (3.10, 3.11, 3.12, 3.13, 3.14, 3.14t)

  3. Release & Publish: Dual-trigger workflow for flexible release management

Note: Python 3.14t is the free-threaded build (without GIL) for testing true parallelism.

Creating a New Release

The release workflow supports two approaches:

Option 1: Automated Release (Recommended)

Push a tag to automatically create a release and publish to PyPI:

# 1. Update version in pyproject.toml
# Edit the version field manually, e.g., "1.0.0" -> "1.1.0"

# 2. Update __version__ in src/mcp_server_whisper/__init__.py to match

# 3. Update the lock file
uv lock

# 4. Commit the version bump
git add pyproject.toml src/mcp_server_whisper/__init__.py uv.lock
git commit -m "chore: bump version to 1.1.0"

# 5. Create and push the version tag
git tag v1.1.0
git push origin main
git push origin v1.1.0

This will:

  • Verify the tag version matches pyproject.toml

  • Build the package

  • Create a GitHub release with auto-generated notes

  • Automatically publish to PyPI

Option 2: Manual Release

Create a release manually via GitHub UI, then publish optionally:

  1. Go to Releases on GitHub

  2. Click "Draft a new release"

  3. Create a new tag or select an existing one

  4. Fill in release details

  5. Click "Publish release"

When you publish the release, the workflow will automatically publish to PyPI. You can also create a draft release to delay publishing.

API Design Philosophy

MCP Server Whisper follows a flat, type-safe API design optimized for MCP clients:

  • Flat Arguments: All tools accept flat parameters instead of nested objects for simpler, more intuitive calls

  • Type-Safe Responses: Every tool returns a strongly-typed Pydantic model (TranscriptionResult, ChatResult, AudioProcessingResult, TTSResult)

  • Single-Item Operations: One call processes one file, with MCP protocol handling parallelism natively

  • Per-File Error Handling: Failures are isolated to individual operations, not entire batches

  • Self-Documenting: Type hints provide autocomplete and validation in IDEs and AI models

This design makes it significantly easier for AI assistants to use the tools correctly and handle results reliably.

How It Works

For detailed architecture information, see Architecture Documentation.

MCP Server Whisper is built on the Model Context Protocol, which standardizes how AI models interact with external tools and data sources. The server:

  1. Exposes Audio Processing Capabilities: Through standardized MCP tool interfaces with flat, type-safe APIs

  2. Implements Parallel Processing: Using anyio structured concurrency; MCP clients handle parallelism natively

  3. Manages File Operations: Handles detection, validation, conversion, and compression

  4. Provides Rich Transcription: Via different OpenAI models and enhancement templates

  5. Optimizes Performance: With caching mechanisms for repeated operations

  6. Ensures Type Safety: All responses use Pydantic models for validation and IDE support

Under the hood, it uses:

  • pydub for audio file manipulation (with audioop-lts for Python 3.13+)

  • anyio for structured concurrency and task group management

  • aioresult for collecting results from parallel task groups

  • OpenAI's latest transcription models (including gpt-4o-transcribe)

  • OpenAI's GPT-4o audio models for enhanced understanding

  • OpenAI's gpt-4o-mini-tts for high-quality speech synthesis

  • FastMCP for simplified MCP server implementation

  • Type hints and strict mypy validation throughout the codebase

Contributing

Contributions are welcome! Please follow these steps:

  1. Fork the repository

  2. Create a new branch for your feature (git checkout -b feature/amazing-feature)

  3. Make your changes

  4. Run the tests and linting (uv run pytest && uv run ruff check src && uv run mypy --strict src)

  5. Commit your changes (git commit -m 'Add some amazing feature')

  6. Push to the branch (git push origin feature/amazing-feature)

  7. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Available Tools

8 tools
chat_with_audioC

A tool used to chat with audio files. The response will be a response to the audio file sent. It is recommended to use gpt-4o-audio-preview by default for best results. Note: gpt-4o-mini-audio-preview has limitations with audio chat and may not process audio correctly.

ParametersJSON Schema
NameRequiredDescriptionDefault
input_file_nameYes
modelNogpt-4o-audio-preview
system_promptNo
user_promptNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
textYesThe response text from the audio chat

TDQS

C2.7/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 cover behavior. It only discusses model limitations; it omits important traits like processing time, authentication needs, or that the tool generates a response.

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 brief (three sentences) and front-loaded with the core purpose. It avoids unnecessary words, but could be better structured by grouping model advice separately.

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

Completeness2/5

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

Despite having an output schema and four parameters, the description does not explain the output or the optional parameters (system_prompt, user_prompt). The advice on models is helpful but overall incomplete for effective tool invocation.

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

Parameters2/5

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

Schema coverage is 0%, so description must explain parameters. It covers the model parameter with recommendations, but input_file_name, system_prompt, and user_prompt receive no explanation beyond what the schema provides.

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

Purpose4/5

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

The description clearly states the tool chats with audio files, which distinguishes it from sibling tools like compress or transcribe. However, it does not specify what type of response is returned (e.g., text or audio), leaving slight ambiguity.

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

Usage Guidelines2/5

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

Only recommends a default model and warns about the mini variant, but does not explain when to use this tool versus alternatives or provide context on prerequisites like audio file format.

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

compress_audioA

A tool used to compress audio files which are >25mb. ONLY USE THIS IF THE USER REQUESTS COMPRESSION OR IF OTHER TOOLS FAIL DUE TO FILES BEING TOO LARGE.

ParametersJSON Schema
NameRequiredDescriptionDefault
input_file_nameYes
max_mbNo
output_file_nameNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
output_fileYesName of the processed audio file

TDQS

A4.1/5.0
Behavior4/5

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

With no annotations, the description carries the burden. It reveals the action (compression) and trigger condition (>25MB), but does not detail output format, quality impact, or reversibility. However, the parameter output_file_name hints at a new file, so it's fairly transparent.

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?

Two sentences, no waste. Could combine the conditional into a single sentence, but it remains efficient and front-loaded with purpose.

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?

Provides core purpose and usage conditions, but lacks detail on parameters and output schema. Since output schema exists, return value explanation is not required, but parameter explanations are missing for a tool with 3 parameters.

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

Parameters2/5

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

Schema has 0% description coverage, so description must explain parameters. It mentions file size >25MB but does not explain max_mb (target size) or output_file_name, missing a chance to clarify their roles.

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 tool compresses audio files larger than 25MB, with a specific verb ('compress') and resource ('audio files'), and distinguishes from sibling tools by its compression focus.

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?

Explicitly states when to use: only when user requests compression or when other tools fail due to file size. This provides clear context and exclusions, guiding the agent appropriately.

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

convert_audioB

A tool used to convert audio files to mp3 or wav which are gpt-4o compatible.

ParametersJSON Schema
NameRequiredDescriptionDefault
input_file_nameYes
target_formatNomp3
output_file_nameNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
output_fileYesName of the processed audio file

TDQS

B3.2/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 cover behavioral details. It only states the conversion action without mentioning side effects (e.g., file overwriting), input/output constraints, or required permissions. Essential transparency for a mutation tool is missing.

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

Conciseness5/5

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

The description is a single, concise sentence (18 words) that conveys the core purpose without unnecessary words. It is front-loaded and efficient.

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 simplicity of the tool (3 parameters, conversion task) and the presence of an output schema, the description is partially complete. However, it omits details on input file format requirements, error scenarios, and output file naming conventions, which are needed for full autonomy.

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

Parameters2/5

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

With 0% schema description coverage, the description needs to explain parameters thoroughly. It implies that input_file_name is the source audio, target_format is mp3/wav, and output_file_name is optional, but does not provide specific format details, default behaviors, or constraints beyond the 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 the tool's purpose: converting audio files to mp3 or wav formats, which are compatible with gpt-4o. It specifies the verb 'convert' and the resource 'audio files', and distinguishes it from sibling tools like transcribe_audio or compress_audio.

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

Usage Guidelines2/5

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention when conversion is appropriate, nor does it exclude cases where other tools like compress_audio or transcribe_audio might be better. The only implied usage is for format conversion.

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

create_audioC

Create text-to-speech audio using OpenAI's TTS API with model and voice selection.

ParametersJSON Schema
NameRequiredDescriptionDefault
text_promptYes
modelNogpt-4o-mini-tts
voiceNoalloy
instructionsNo
speedNo
output_file_nameNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
output_fileYesName of the generated audio file

TDQS

C2.7/5.0
Behavior2/5

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

With no annotations, the description should disclose behavioral traits like output format, file storage behavior, or rate limits. It only states it creates audio, lacking details on whether it saves to disk, returns a URL, or any potential side effects.

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

Conciseness2/5

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

The description is a single sentence, but it is too terse to be informative. It omits important details about parameters, behavior, and usage, making it under-specified rather than concise.

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

Completeness1/5

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

Given 6 parameters and no schema descriptions, the description is severely incomplete. It does not mention the output schema, return value, or any context about the API being called (e.g., authentication, latency). An agent would lack critical information to invoke this tool correctly.

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

Parameters2/5

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

Schema description coverage is 0%, so the description must add meaning to parameters. It only mentions model and voice selection, ignoring text_prompt, instructions, speed, and output_file_name. No parameter-level details are provided beyond the schema names.

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 it creates text-to-speech audio using OpenAI's TTS API, specifying model and voice selection. This distinguishes it from sibling tools like transcribe_audio or compress_audio.

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

Usage Guidelines2/5

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

No guidance on when to use this tool versus alternatives like transcribe_audio or chat_with_audio. It does not mention prerequisites, such as API key requirements, or scenarios where this tool is preferred.

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

get_latest_audioA

Get the most recent audio file from the audio path. ONLY USE THIS IF THE USER ASKS FOR THE LATEST FILE.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
file_nameYesName of the audio file
transcription_supportNoList of transcription models that support this file format
chat_supportNoList of audio LLM models that support this file format
modified_timeYesLast modified timestamp of the file (Unix time)
size_bytesYesSize of the file in bytes
formatYesAudio format of the file (e.g., 'mp3', 'wav')
duration_secondsNoDuration of the audio file in seconds, if available

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 must disclose behavioral traits. It only states 'from the audio path' without defining the path, how 'most recent' is determined, or what the output format is. This lacks sufficient detail for an agent to understand the tool's behavior.

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

Conciseness5/5

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

The description is extremely concise with two sentences, no wasted words, and a clear directive. Every sentence adds value.

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?

The tool has no parameters and an output schema (unknown content). The description is minimal and lacks context about the 'audio path' and how the latest is determined. While simple, it leaves gaps for an agent that may need more context about the environment.

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?

There are no parameters, so schema coverage is 100%. The description does not need to add param info, and the baseline for no parameters is 4. No additional semantics are required.

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 tool retrieves the most recent audio file, using specific verb 'get' and resource. It differentiates from sibling tools by specifying a unique action (getting the latest file) and includes an explicit usage condition.

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 description explicitly provides a usage guideline: 'ONLY USE THIS IF THE USER ASKS FOR THE LATEST FILE.' This tells the agent exactly when to invoke the tool and implicitly when not to, which is sufficient for decision-making.

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

list_audio_filesC

List, filter, and sort audio files from the audio path. Supports regex pattern matching, filtering by metadata (size, duration, date, format), and sorting.

ParametersJSON Schema
NameRequiredDescriptionDefault
patternNo
min_size_bytesNo
max_size_bytesNo
min_duration_secondsNo
max_duration_secondsNo
min_modified_timeNo
max_modified_timeNo
formatNo
sort_byNoname
reverseNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.9/5.0
Behavior3/5

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

Without annotations, the description implies a read-only operation (list/filter) but does not explicitly state that no modifications occur. It also lacks information about required permissions, error handling, or behavior when the audio path is empty or invalid.

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 a single sentence that front-loads key actions and capabilities. It is efficient but could be slightly more structured with bullet points for clarity.

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

Completeness2/5

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

Given the many filter parameters and the existence of an output schema, the description does not explain the return structure or pagination. It also omits context about the 'audio path' (fixed or parameter).

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

Parameters2/5

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

With 10 parameters and 0% schema description coverage, the description only lists high-level categories (regex, metadata filters, sorting) without detailing what each parameter does. For instance, 'pattern' is not explained as a regex, and range parameters lack format hints.

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

Purpose4/5

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

The description uses clear action verbs ('List, filter, and sort') and specifies the resource ('audio files from the audio path'). However, it does not differentiate this tool from siblings like 'get_latest_audio' which could also list files.

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

Usage Guidelines2/5

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

No guidance is provided on when to use this tool versus its siblings or alternatives. There is no mention of prerequisites, limitations, or when not to use this tool.

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

transcribe_audioC

A tool used to transcribe audio files. It is recommended to use gpt-4o-mini-transcribe by default. If the user wants maximum performance, use gpt-4o-transcribe. Rarely should you use whisper-1 as it is least performant, but it is available if needed. You can use prompts to guide the transcription process based on the users preference.

ParametersJSON Schema
NameRequiredDescriptionDefault
input_file_nameYes
modelNogpt-4o-mini-transcribe
response_formatNotext
promptNo
timestamp_granularitiesNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
textYesThe transcribed text
durationNoDuration of the audio in seconds
languageNoDetected language of the audio
segmentsNoTimestamped segments
wordsNoWord-level timestamps
usageNoToken usage information
logprobsNoLog probabilities if requested

TDQS

C2.9/5.0
Behavior2/5

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

No annotations provided; the description only mentions model recommendations and prompt usage. It does not disclose behaviors like rate limits, data handling, or side effects.

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 relatively short with three sentences. It is front-loaded with the core purpose, but the opening sentence is somewhat generic.

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

Completeness2/5

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

An output schema exists but is not referenced. For a tool with 5 parameters and multiple enum options, the description lacks detail on response formats and required fields.

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

Parameters2/5

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

Schema coverage is 0%, and the description adds little value beyond the schema. Only 'prompt' is briefly mentioned; parameters like 'input_file_name', 'response_format', and 'timestamp_granularities' are not explained.

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

Purpose4/5

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

Clearly states the tool transcribes audio files. The verb 'transcribe' and resource 'audio files' are specific, but it does not differentiate from sibling tools like 'transcribe_with_enhancement'.

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?

Provides model selection guidance (default, performance, rare use) but does not address when to use this tool over alternatives like 'chat_with_audio' or 'transcribe_with_enhancement'.

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

transcribe_with_enhancementB

Transcribe audio with GPT-4 using specific enhancement prompts.

    Enhancement types:
    - detailed: Provides detailed description including tone, emotion, and background
    - storytelling: Transforms the transcription into a narrative
    - professional: Formats the transcription in a formal, business-appropriate way
    - analytical: Includes analysis of speech patterns, key points, and structure

    Args:
        input_file_name: Name of the input audio file to process
        enhancement_type: Type of enhancement to apply to the transcription
        model: The transcription model to use
        response_format: The response format
        timestamp_granularities: Optional timestamp granularities

    Returns:
    -------
        TranscriptionResult with enhanced transcription
ParametersJSON Schema
NameRequiredDescriptionDefault
input_file_nameYes
enhancement_typeNodetailed
modelNogpt-4o-mini-transcribe
response_formatNotext
timestamp_granularitiesNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
textYesThe transcribed text
durationNoDuration of the audio in seconds
languageNoDetected language of the audio
segmentsNoTimestamped segments
wordsNoWord-level timestamps
usageNoToken usage information
logprobsNoLog probabilities if requested

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 carry full burden. It discloses enhancement behavior and model usage (GPT-4), but does not mention side effects like cost, latency, authentication needs, or prerequisites (e.g., file upload). Critical operational details are missing.

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?

Description is well-structured with a summary, enhancement type list, Args, and Returns sections. It is front-loaded with purpose. Some redundancy in repeating parameter names from schema, and the 'Returns' line is vague. Overall efficient but not maximally concise.

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 5 parameters, no annotations, and a sibling transcribe tool, the description covers the main functionality and enhancement types. However, it lacks output schema details, prerequisites, and explanation of defaults (e.g., enhancement_type defaults to 'detailed'). Adequate for basic use but incomplete for nuanced decisions.

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?

Schema coverage is 0%, requiring the description to add meaning. The 'Args' section gives brief explanations (e.g., 'Name of the input audio file to process'), which is adequate but not rich. With 5 parameters and enums partially conveying meaning, the description adds marginal value but does not fully compensate for the coverage gap.

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?

Description clearly states 'Transcribe audio with GPT-4 using specific enhancement prompts', specifying verb and resource, and distinguishes from siblings like transcribe_audio by adding enhancement capability. Lists four distinct enhancement types with their purposes.

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?

Implies usage when enhanced transcription is needed through the list of enhancement types, but lacks explicit guidance on when to use this tool versus the transcribe_audio sibling. No exclusions or alternatives are mentioned beyond the implied difference.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 8 tool updatesv1.0.0
    • First observedchat_with_audio
    • First observedcompress_audio
    • First observedconvert_audio
    • First observedcreate_audio
    • First observedget_latest_audio
    • First observedlist_audio_files
    • First observedtranscribe_audio
    • First observedtranscribe_with_enhancement
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.4/5.0

Scored across 8 tools

Disambiguation3/5

Most tools have clear single-action purposes (convert, compress, chat, create, list, get-latest), but transcribe_audio and transcribe_with_enhancement are very similar in function and could be easily confused, despite the enhancement descriptor. Descriptions and usage clues help, but the overlapping transcription surface creates some misselection risk.

Naming Consistency4/5

Tool names generally follow a verb_noun pattern in lowercase snake_case (list_audio_files, convert_audio, compress_audio, create_audio). Slight deviations exist with get_latest_audio, chat_with_audio, and transcribe_with_enhancement, which break the clean noun-object structure, but the pattern remains readable and predictable.

Tool Count5/5

Eight tools cover the full audio processing workflow—file access, format preparation, size handling, transcription, enhanced transcription, chat, and TTS—without unnecessary redundancy. Each tool earns its place and the count is well within the ideal range for a focused MCP server.

Completeness4/5

The surface is quite complete for a Whisper/audio media server: it supports listing, retrieving, converting, compressing, transcribing, enhanced transcription, audio chat, and TTS synthesis. Minor gaps such as no audio preview or batch processing exist, but agents can work around them with available tools.

Maintenance

ActivityInactive
ResponsivenessUnresponsive

Resources

Related MCP Connectors

Related MCP Servers