Transcription MCP Sever

Transcription MCP Sever

一个使用 AssemblyAI API 转录 MP3 音频文件的 MCP（Model-Context-Protocol）服务。此服务提供命令行和基于 Docker 的音频转录工具。Podcaster、内容创作者、教育工作者和业务团队都可以使用此应用，让工作更轻松。

功能

• 通过命令行界面接收 .mp3 文件
• 接收由 Claude 或 Cursor 等 AI 助手提供的 .mp3 文件路径
• 使用 AssemblyAI API 将 MP3 音频文件转录为 JSON 文稿
• 为每个转录片段添加时间戳，包括开始和结束时间
• 启用说话人分离（说话人标签）
• 将文稿保存到本地的 transcripts/ 目录
• 已准备好在 Docker 容器中运行，便于移植和部署

系统架构概述

此应用是一个用于通过 AssemblyAI 转录音频文件的微服务。

架构细分

• Uvicorn 作为 MCP 服务运行时：Uvicorn 运行服务进程，作为执行转录任务的入口点。
• AssemblyAI 客户端：此组件负责处理与 AssemblyAI API 的所有通信。
• 通过 Google Fire 提供 CLI：应用包含一个使用 Google Fire 构建的强大命令行界面。用户可以直接在终端中转录音频文件
• Docker 化环境：虽然可以直接在本地计算机上运行此服务，但它也包含轻量级 Docker 配置，供偏好容器化部署的用户使用。

开始使用

前置条件

• Python 3.10+（稳定、流行且支持完善）
• Uvicorn（轻量级 ASGI 服务端）
• Google Fire（CLI 框架，可简单高效地创建 CLI）
• AssemblyAI API 密钥（API 接口，请访问 https://www.assemblyai.com/ 注册）
• Docker（可选，用于容器化运行，确保部署一致且易于移植）

安装

1. 克隆仓库：

git clone <your-repo-url>
cd <repo-folder> 

2. 安装依赖：

pip install -r requirements.txt

3. 将 AssemblyAI API 密钥设置为环境变量：

export API_KEY="your_assemblyai_api_key"   # Linux / macOS
set API_KEY="your_assemblyai_api_key"      # Windows CMD

使用方法

使用 MCP Dev 检查

运行此命令，通过 Web UI 检查并测试工具的功能。

uv run mcp dev mcp/server_transcription.py

连接并测试 server_transcription

运行命令以连接 Claude

uv run mcp install mcp\server_transcription.py

JSON 格式

连接 Claude 或 Cursor 等 AI 助手时，配置应采用以下 JSON 格式。

{
  "mcpServers": {
    "Audio Transcription Service": {
      "command": "C:\\Users\\HomePC\\Desktop\\mcp_task2\\.venv\\Scripts\\python.exe",
      "args": [
        "-u",
        "C:\\Users\\HomePC\\Desktop\\mcp_task2\\mcp\\server_transcription.py"
      ],
      "env": {
        "API_KEY": "<input-your-api-key-here>"
      }
    }
  }
}

测试 client_transcription

运行命令

python  mcp\client_transcription.py "path/to/audio/file"

Docker 使用方法

构建 Docker 镜像

docker build -t transcription-service -f run_with_docker/Dockerfile .

运行 Docker 容器

set API_KEY="your-api-key-here"

docker run -d -p 8050:8050 -e API_KEY=%API_KEY% -v C:\Users:/mnt/users -v %CD%\transcripts:/app/transcripts -v %CD%\logs:/app/logs --dns 8.8.8.8 --name transcription-server transcription-service

运行客户端

python run_with_docker\client.py "path/to/audio/file"