使用说明

长尾小鹦鹉转录MCP服务器

版本： 0.1.0

这是一个MCP（模型上下文协议）服务器，旨在使用NVIDIA强大的Parakeet TDT 0.6B V2模型将音频和视频文件转录为文本。它还提供了获取模型本身详细信息的工具。

该服务器采用FastMCP构建，依赖于 pydub （需要FFmpeg）用于处理音频转换和 nemo_toolkit[asr] 核心转录能力。

重要提示： 必须在系统的PATH中安装并访问FFmpeg。提供给服务器工具的所有文件路径都必须是绝对路径。

快速启动

以下是让服务器运行的步骤的简要概述：

安装先决条件： 确保你有 mise, uv，以及转码已安装并可在系统的PATH中访问。请参阅先决条件详情请参阅第节。
克隆存储库： 如果还没有，请克隆此存储库并导航到项目目录。
设置环境： 使用 mise 安装正确的Python版本并激活环境：
```
mise install
```
安装依赖关系： 使用 uv 安装所需的Python包：
```
uv pip install -r requirements.txt
```
运行服务器： 使用启动MCP服务器 fastmcp:
```
fastmcp run server.py
```
服务器通常会开始使用STDIO传输。看运行服务器对于HTTP等其他选项。

服务器运行后，您可以使用兼容MCP的客户端与之交互。看与服务器交互（客户端使用）例如。

关于ASR型号：NVIDIA鹦鹉TDT 0.6B V2（英文）

该服务器采用NVIDIA Parakeet TDT 0.6B V2型号，这是一种具有6亿个参数的FastConformer架构。它针对高质量的英语转录进行了优化，具有精确的单词级时间戳、自动标点和大写，以及在口语数字和歌词上的强大性能。它可以在一次传输中高效地转录长达24分钟的音频片段。

输入： 16kHz音频（WAV或FLAC），单声道。
输出： 带有可选标点符号、大写字母和时间戳的文本。
许可证： CC-BY-4.0。
演示和更多信息： 拥抱面部空间

虽然针对NVIDIA GPU进行了优化，但如果未检测到兼容的GPU，该模型将退回CPU（注意：CPU性能可能会明显变慢）。

特性

转录各种音频/视频格式。
自动将输入音频转换为所需的16kHz、单声道WAV或FLAC格式。
选项包括详细的单词和分段时间戳。
当包含时间戳时，格式化的转录输出带有可定制的换行符。
检索有关加载的ASR模型的信息。
检索系统硬件规格（操作系统、CPU、RAM、GPU）。

先决条件

python 版本3.12（如中所述 .tool-versions 和 mise.toml).
mise: 用于管理Python版本（和其他工具）。安装 mise 按照官方的 mise 文档.
uv: 一个非常快的Python包安装程序和解析器。安装 uv 按照以下说明星体 uv 文档.
FFmpeg： 要求的 pydub 用于音频和视频文件格式转换。必须在系统的PATH中安装并访问FFmpeg。
- macOS（使用Homebrew）：
```
brew install ffmpeg
```
- Linux（使用apt-Debian/Ubuntu）：
```
sudo apt update && sudo apt install ffmpeg
```
- Linux（使用yum-CentOS/RHEL/Fedora）：
```
sudo yum install ffmpeg  # Or dnf for newer Fedora: sudo dnf install ffmpeg
```
- 窗户： 从下载FFmpeg FFmpeg官方网站.提取存档并添加 bin 目录（包含 ffmpeg.exe)到系统的PATH环境变量。
- 验证FFmpeg安装： 打开一个新的终端/命令提示符，然后键入：
```
ffmpeg -version
```
  如果安装正确，您应该看到版本信息。

设置和安装

克隆存储库（如果您还没有）：

# git clone https://github.com/MiguelsPizza/local-transcription-mcp--parakeet-tdt-0.6b-v2--.git
# cd <repository-directory>

使用以下命令设置Python版本 mise: 导航到终端中的项目目录并运行：
```
mise install
```
这将确保您按照中的指定使用Python 3.12 .tool-versions.
使用安装Python依赖项 uv: 确保你的 mise 环境处于活动状态（如果您 cd 进入目录后 mise install).然后运行：
```
uv pip install -r requirements.txt
```
这将安装 fastmcp, pydub, nemo_toolkit[asr], psutil以及其他必要的包。

运行服务器

MCP服务器

fastmcp dev server.py

要在生产中运行：

fastmcp run server.py

FastAPI服务器（用于REST API）

要使用RESTneneneba API，如果您还没有安装其他依赖项，则需要首先安装这些依赖项（包括 fastapi, uvicorn，以及 python-multipart):

# Ensure your mise environment is active
uv pip install -r requirements.txt

然后，从项目根目录使用Uvicorn运行FastAPI应用程序：

# From the root of the project (transcription-mcp)
uvicorn api.main:app --host 0.0.0.0 --port 8000 --reload

api.main:app 告诉Uvicorn寻找一个名为 app 在 main.py 文件内部 api 目录。
--host 0.0.0.0 使服务器可以从网络上的其他设备访问。
--port 8000 指定要运行的端口。
--reload 启用代码更改时的自动重新加载，这对开发很有用。

一旦运行，API将可以访问 http://localhost:8000 （或端口8000上的计算机IP地址）。交互式API文档（Swagger UI）将在 http://localhost:8000/docs.

可用组件（API）

服务器通过两个接口公开功能：模型上下文协议（MCP）和RESTful HTTP API。

MCP服务器组件

以下组件可通过MCP服务器获得(server.py):

工具

1. `transcribe_audio`

说明： 使用Parakeet TDT 0.6B V2型号将音频/视频文件转录为文本。
参数：
- audio_file_path （字符串， 绝对路径，必填）：要转录的音频或视频文件的绝对路径。
- output_format （字符串，可选，默认值： "wav")：在转录之前将输入文件转换为的中间音频格式。支持的值： "wav", "flac".
- include_timestamps （布尔值，可选，默认值： True)：是否在转录输出中包含单词和分段级别的时间戳。
- line_character_limit （整数，可选，默认值： 80，min:40，max:200）：当包含时间戳时，格式化转录输出的每行字符限制。
- segment_length_minutes （整数，可选，默认值： 5，min:1，max:24）：音频片段的最大长度（分钟）。超过此长度的音频将被分割。
退货： JSON对象包含：
- message （string）：指示转录结果的状态消息。
- file_processed （string）：原始 audio_file_path 已处理。
- transcription （string）：转录的文本，可能用时间戳格式化。

2.系统硬件规格

URI： info://system_hardware_specs
姓名： system_hardware_specifications
说明： 检索与性能估计相关的系统硬件规格，如操作系统、CPU、RAM和GPU详细信息。
退货： 包含系统硬件详细信息的JSON对象（请参见 server.py 完整结构）。

REST API端点（FastAPI）

以下端点可通过FastAPI服务器使用(api/main.py)，通常在上运行 http://localhost:8000:

1.转录音频

端点： POST /transcribe/
说明： 转录上传的音频或视频文件。
请求类型： multipart/form-data
表单字段：
- file （文件，必填）：要转录的音频或视频文件。
- output_format （字符串，可选，默认值： "wav")：中间音频格式("wav" 或 "flac").
- include_timestamps （布尔值，可选，默认值： True)：是否包括单词/段时间戳。
- line_character_limit （整数，可选，默认值： 80，最小值：40，最大值：200）：带时间戳输出的每行字符限制。
- segment_length_minutes （整数，可选，默认值： 5，min:1，max:24）：最大音频段长度（分钟）。

成功响应（200 OK）：

{
  "message": "Transcription successful with formatted timestamps.",
  "file_processed": "your_audio_file.mp3",
  "transcription": "The transcribed text..."
}

错误响应（例如，400、422、500）： JSON对象 detail 描述错误的字段。

2.ASR车型信息

端点： GET /info/asr-model/
说明： 提供有关ASR模型的详细信息。

成功响应（200 OK）：

{
  "model_name": "NVIDIA Parakeet TDT 0.6B V2 (En)",
  "status": "Loaded",
  "input_requirements": "16kHz Audio (.wav or .flac), Monochannel",
  "output_type": "Text with optional Punctuation, Capitalization, and Timestamps.",
  "license": "CC-BY-4.0",
  "note": "This model is optimized for NVIDIA GPU-accelerated systems."
}

3.系统硬件规格

端点： GET /info/system-hardware/
说明： 检索系统硬件规格。

成功响应（200 OK）： 包含系统硬件详细信息的JSON对象（请参见 api/main.py SystemHardwareResponse 全结构模型）。

// Example structure (fields may vary based on system)
{
  "os_platform": "Darwin",
  "os_version": "...",
  "cpu_model": "Apple M1 Pro",
  "ram_total_gb": 16.0,
  "cuda_available": false,
  "gpus": [
    {
      "name": "Apple Metal Performance Shaders (MPS)",
      "memory_total_gb": "N/A (Shared with System Memory)",
      "notes": "MPS is available for PyTorch on this Mac."
    }
  ]
  // ... other fields ...
}

添加到MCP客户端主机

您可以配置MCP客户端（如Claude Desktop或其他支持自定义MCP服务器定义的工具）以使用此服务器。

手动JSON配置

对于使用JSON配置文件的客户端（例如。， cline_mcp_settings.json 或类似）来定义MCP服务器，您可以为此转录服务器添加一个条目。确保您已完成上述“设置和安装”步骤，以便在客户端尝试运行服务器时，Python 3.12和所有依赖项在您的环境中可用。

以下是一个示例配置片段：

{
  "mcpServers": {
    "transcription-mcp": {
      "autoApprove": [],
      "disabled": true,
      "timeout": 600,
      "command": "uv",
      "args": [
        "run",
        "--with",
        "fastmcp",
        "--with",
        "nemo_toolkit[asr]",
        "--with",
        "pydub",
        "psutil",
        "fastmcp",
        "run",
        "/absolute/path/to/this/file/server.py"
      ],
      "env": {},
      "transportType": "stdio"
    }
    // ... other server configurations ...
  }
}

使用 `fastmcp install` （适用于受支持的客户）

一些MCP客户端，如最新版本的Claude Desktop App，与 fastmcp install 命令。这可以通过为服务器创建隔离环境来简化设置。如果您的客户端支持此功能，您可以使用以下命令从该项目的根目录安装服务器：

fastmcp install server.py -e . -n "Parakeet Transcription Server"

-e .：安装当前目录（应包含 pyproject.toml)在可编辑模式下。这 pyproject.toml 文件列出了核心依赖项(fastmcp, pydub, nemo_toolkit[asr], psutil)，其中 fastmcp install 应该捡起来。
-n "Parakeet Transcription Server"：在客户端应用程序中为服务器设置自定义名称。

此命令通常会处理打包服务器及其指定的依赖关系以供客户端使用。

与服务器交互（客户端使用）

您可以使用任何与FastMCP兼容的客户端与此MCP服务器进行交互。下面是一个使用Python的基本示例 fastmcp 图书馆：

import asyncio
from fastmcp import Client

# If running the MCP server with 'fastmcp run server.py' (defaulting to STDIO):
client = Client("server.py")

# If running the server with HTTP, e.g., 'fastmcp run server.py --transport streamable-http --port 8000':
# client = Client("http://localhost:8000/mcp")

# If you've added it to your client's host configuration (e.g., Claude Desktop)
# and the client library allows referencing by name/ID:
# client = Client(mcp_server_id="parakeet-transcription-server-local") # Syntax depends on client library

async def main():
    async with client:
        print(f"Client connected: {client.is_connected()}")

        # Example 1: Get ASR Model Information
        try:
            print("\nFetching ASR model info...")
            model_info_result = await client.call_tool("get_asr_model_info")
            # Assuming the result is a JSON string in the first TextContent part
            model_info_dict = model_info_result[0].text_content_as_json_dict()
            print("ASR Model Info:")
            for key, value in model_info_dict.items():
                 print(f"  {key}: {value}")
        except Exception as e:
            print(f"Error calling get_asr_model_info: {e}")

        # Example 2: Transcribe an audio file (replace with an ACTUAL absolute path)
        # Ensure the audio file exists and the path is absolute.
        audio_file_to_transcribe = "/Users/yourname/path/to/your/audio.mp3" # <<< REPLACE THIS
        #
        if audio_file_to_transcribe != "/Users/yourname/path/to/your/audio.mp3": # Basic check
            try:
                print(f"\nTranscribing '{audio_file_to_transcribe}'...")
                transcription_args = {
                    "audio_file_path": audio_file_to_transcribe,
                    "include_timestamps": True,
                    "output_format": "wav" # or "flac"
                }
                transcription_result = await client.call_tool("transcribe_audio", transcription_args)
                # Assuming the result is a JSON string in the first TextContent part
                result_data = transcription_result[0].text_content_as_json_dict()
                print(f"File Processed: {result_data.get('file_processed')}")
                print(f"Message: {result_data.get('message')}")
                print("Transcription Output:")
                print(result_data.get('transcription'))
            except Exception as e:
                print(f"Error calling transcribe_audio: {e}")
        else:
            print("\nPlease update 'audio_file_to_transcribe' with an actual absolute file path to test transcription.")

    print(f"\nClient disconnected: {client.is_connected()}")

if __name__ == "__main__":
    asyncio.run(main())

注：对于转录示例，请确保替换`

音频转录服务器

使用说明

长尾小鹦鹉转录MCP服务器

快速启动

关于ASR型号：NVIDIA鹦鹉TDT 0.6B V2（英文）

特性

先决条件

设置和安装

运行服务器

MCP服务器

FastAPI服务器（用于REST API）

可用组件（API）

MCP服务器组件

工具

1. `transcribe_audio`

2.系统硬件规格

REST API端点（FastAPI）

1.转录音频

2.ASR车型信息

3.系统硬件规格

推荐的转录工作流程

添加到MCP客户端主机

手动JSON配置

使用 `fastmcp install` （适用于受支持的客户）

与服务器交互（客户端使用）

使用说明

长尾小鹦鹉转录MCP服务器

快速启动

关于ASR型号：NVIDIA鹦鹉TDT 0.6B V2（英文）

特性

先决条件

设置和安装

运行服务器

MCP服务器

FastAPI服务器（用于REST API）

可用组件（API）

MCP服务器组件

工具

1. transcribe_audio

2.系统硬件规格

REST API端点（FastAPI）

1.转录音频

2.ASR车型信息

3.系统硬件规格

推荐的转录工作流程

添加到MCP客户端主机

手动JSON配置

使用 fastmcp install （适用于受支持的客户）

与服务器交互（客户端使用）

相关 MCP

语音处理服务

LLM增强工具包

Ableton音乐制作辅助工具

音频接口服务器

语音合成服务器

音频转录处理服务

1. `transcribe_audio`

使用 `fastmcp install` （适用于受支持的客户）