FunASR MCP Server 实战指南为 AI 助手接入本地语音转录能力【免费下载链接】FunASROpen-source speech recognition toolkit for training, inference, streaming ASR, VAD, punctuation, speaker diarization pipelines, and OpenAI-compatible/MCP serving.项目地址: https://gitcode.com/GitHub_Trending/fun/FunASRFunASR MCP Server 是 FunASR 仓库中基于 Model Context ProtocolMCP实现的服务端程序它把 FunASR 的语音识别能力封装成一个标准 MCP 工具让 Claude Code、Claude Desktop、Cursor、Windsurf 等 AI 助手可以直接转录本机音频文件。读完本文你将掌握该 MCP 服务器的完整原理、部署方式源码直跑与 Docker、客户端接入配置、工具调用契约以及将其发布到官方 MCP Registry 和 Glama 目录的完整流程。一、MCP 与 FunASR 的结合点Model Context Protocol 是 AI 助手与外部工具之间的标准化通信协议。FunASR MCP Server 的角色是把 AutoModel 的推理能力翻译成 MCP 工具AI 助手通过 JSON-RPC 协议与服务器通信服务器在本地完成音频文件加载、VAD 切分、语音识别再把转录文本返回给助手。整个过程完全在本地进行音频数据不会离开用户机器无需任何 API Key。该服务器默认加载iic/SenseVoiceSmall模型支持普通话、粤语、英语、日语、韩语五种语言的识别并通过 fsmn-vad 模型对长音频先做 VAD 切分再识别。二、目录结构与核心文件整个 MCP Server 位于 examples/mcp_server 目录包含以下文件文件作用funasr_mcp.pyMCP 服务器主程序实现 stdio 传输、JSON-RPC 处理与转录工具Dockerfile容器镜像定义内置 FunASR 依赖与启动命令server.json官方 MCP Registry 的版本化元数据glama.jsonGlama 目录扫描所需的容器命令与元数据smoke_test.py容器冒烟测试验证 MCP 握手与 tools/listtest_funasr_mcp.py单元测试工具契约、参数校验、错误处理test_registry_metadata.py元数据一致性测试server.json 与 Dockerfile 等互相对齐主程序 funasr_mcp.py 中两个关键常量定义了服务的能力边界DEFAULT_MODEL iic/SenseVoiceSmall SUPPORTED_LANGUAGES (auto, zh, yue, en, ja, ko)三、快速开始源码直跑1. 安装依赖在已安装 Python 的环境中执行pip install funasr2. 直接运行服务器python examples/mcp_server/funasr_mcp.py服务器通过标准输入输出stdio与 MCP 客户端通信因此不需要监听端口。它在启动后等待客户端按行发送 JSON-RPC 消息逐行解析处理。从源码结构看main() 会持续读取sys.stdin对每条 JSON 请求调用handle_request分发处理。3. 手动验证 MCP 握手可以向服务器进程发送两行 JSON-RPC 请求来验证协议是否正常{jsonrpc:2.0,id:1,method:initialize,params:{protocolVersion:2024-11-05,capabilities:{},clientInfo:{name:manual-test,version:1.0}}} {jsonrpc:2.0,id:2,method:tools/list,params:{}}服务器会依次返回initialize结果包含protocolVersion: 2024-11-05、capabilities.tools.listChanged: false和serverInfo以及tools/list结果包含transcribe_audio工具的完整 JSON Schema。四、工具契约transcribe_audio服务器向客户端暴露的唯一工具是transcribe_audio其参数定义如下参数类型必填说明audio_pathstring是音频文件路径wav、mp3、flac、m4a、ogg必须是 MCP 服务器可见的本地文件languagestring否语言提示auto、zh、yue、en、ja或ko默认auto工具返回转录文本并在模型返回分句信息时附带带时间戳的段落。底层调用链与数据清洗从源码看转录核心逻辑在 transcribe()调用model.generate(inputaudio_path, batch_size1, languagelanguage)完成推理用正则re.sub(r\|[^|]*\|, , text)剥离 SenseVoice 输出中的特殊标签如|zh|、|Speech|等富文本标记得到干净文本如果结果包含sentence_info将其逐条转换为segments列表start/end从毫秒转换为秒除以 1000speaker字段透传说话人信息模型支持时才有。在 tools/call 处理 中服务器还会做如下前置校验任一失败即返回isError结果而不触发推理audio_path缺失或为空字符串 → 返回 audio_path is requiredlanguage不在支持枚举内 → 返回 unsupported language ... choose one of: auto, zh, yue, en, ja, koaudio_path经os.path.expanduser展开~后不是存在的文件 → 返回 file not found推理过程抛异常 → 返回 transcription failed: ...且服务器进程不崩溃。这些校验逻辑在 test_funasr_mcp.py 中都有对应的单元测试覆盖空路径、非法语言、~展开、推理异常兜底可以作为理解工具行为的权威依据。五、环境变量配置服务器通过两个环境变量控制推理行为变量默认值说明FUNASR_DEVICEcpu推理设备cuda、cpu或mpsFUNASR_MODELiic/SenseVoiceSmall传入AutoModel的模型名或本地模型路径在 get_model() 中环境变量被组装成 AutoModel 参数_model AutoModel( modelmodel_name, # FUNASR_MODEL 或默认 SenseVoiceSmall vad_modelfsmn-vad, # 启用 VAD 长音频切分 vad_kwargs{max_single_segment_time: 30000}, # 单段最长 30 秒 devicedevice, # FUNASR_DEVICE disable_updateTrue, # 启动时跳过版本检查 )其中model、device、vad_model、vad_kwargs、disable_update都是 AutoModel 的正式参数vad_model用于long audio segmentationvad_kwargs示例值即{max_single_segment_time: 60000}这类配置device支持cuda:0、cpu、mps、npu:0并在设备不可用时回退 CPU。模型采用单例懒加载首次调用工具时才会构建模型此时会下载权重到本地缓存后续调用复用同一实例。使用示例FUNASR_DEVICEcuda FUNASR_MODELiic/SenseVoiceSmall python examples/mcp_server/funasr_mcp.py六、Docker 部署与冒烟测试1. 镜像构建与运行Dockerfile 基于python:3.10-slim安装ffmpeg与libsndfile1音频解码依赖以funasr1.3.29固定版本安装 FunASR并复制funasr_mcp.py作为入口CMD [python, /app/funasr_mcp.py]。docker build -t funasr-mcp examples/mcp_server docker run --rm -i \ -e FUNASR_DEVICEcpu \ --mount typebind,src/path/to/audio,dst/audio,readonly \ --mount typevolume,srcfunasr-mcp-cache,dst/root/.cache/modelscope \ funasr-mcp关键设计点音频目录以只读方式挂载到容器内/audio调用工具时路径需写为/audio/meeting.wav这样的容器内路径模型缓存目录挂载为命名卷funasr-mcp-cache避免每次容器重建都重新下载 ModelScope 模型必须使用-i交互模式因为服务器通过 stdio 传输。2. 冒烟测试无需下载模型smoke_test.py 会向容器发送initialize与tools/list两个标准请求并校验返回两个 JSON 对象、响应 ID 为 1 和 2、serverInfo.name为funasr、工具列表中包含transcribe_audio。由于该测试只做协议握手而不触发推理运行它不会下载模型权重python examples/mcp_server/smoke_test.py funasr-mcp该脚本还具备健壮性检查stdout 中出现非 JSON 日志行会被判定失败这保证了 MCP 行协议newline-delimited JSON-RPC的纯净性。七、接入主流 AI 客户端Claude Code在~/.claude.json中加入{ mcpServers: { funasr: { command: python, args: [/path/to/examples/mcp_server/funasr_mcp.py], env: {FUNASR_DEVICE: cuda} } } }Claude Desktop在claude_desktop_config.json中加入{ mcpServers: { funasr: { command: python, args: [/path/to/funasr_mcp.py], env: {FUNASR_DEVICE: cpu} } } }Cursor在 Settings → MCP Servers → Add 中配置Command:python /path/to/funasr_mcp.pyEnvironment:FUNASR_DEVICEcuda使用示例配置完成后直接向 AI 助手提出自然语言请求即可Transcribe the meeting recording at ~/Downloads/meeting.wavWhat was said in this audio file? /path/to/interview.mp3Convert this voice memo to text: ~/voice_note.m4a八、发布到官方 MCP Registry1. 版本化元数据server.json 是面向官方 MCP Registry 的版本化元数据其核心信息包括命名空间io.github.modelscope/funasr-mcp、版本0.1.2、OCI 包标识ghcr.io/modelscope/funasr-mcp:0.1.2、stdio 传输方式以及两条运行时挂载参数——将宿主机音频目录只读挂载到/audio必须项占位符{audio_directory}以及把模型缓存持久化到命名卷。Dockerfile 中带有与元数据匹配的 OCI 归属标签LABEL io.modelcontextprotocol.server.nameio.github.modelscope/funasr-mcptest_registry_metadata.py 对两者的一致性做了硬性校验server.json中的名字必须与 Dockerfile 的 LABEL 完全一致、server.json版本必须与镜像 tag 一致、README 中引用的镜像 tag 必须与当前版本一致发布新版本后旧 tag 不得残留。2. 发布流程发布新版本的步骤为同步更新server.json中的version与 OCI 镜像 tag等待 MCP 校验工作流通过后合入变更由modelscope组织 Owner 推送匹配的mcp-vversiontag例如mcp-v0.1.2批准受保护的mcp-registry-publish环境部署。发布工作流会自动完成按官方 schema 校验元数据、构建镜像、执行 MCPinitialize与tools/list握手即运行python examples/mcp_server/smoke_test.py、推送版本化镜像到 GHCR、通过官方mcp-publisherCLI 发布server.json。3. 权限与安全官方 Registry 只把io.github.modelscope/*命名空间授予 GitHub 组织 Owner。发布环境必须限制在 release tag 触发、并要求维护者审批因为其 OIDC token 拥有发布组织命名空间的权限。这是发布侧的安全红线切勿放宽。4. 客户端直接拉取已发布镜像发布后任何 MCP 客户端可以直接运行固定版本的镜像docker run --rm -i \ --mount typebind,src/path/to/audio,dst/audio,readonly \ --mount typevolume,srcfunasr-mcp-cache,dst/root/.cache/modelscope \ ghcr.io/modelscope/funasr-mcp:0.1.2容器场景下工具路径需使用容器内路径例如/audio/meeting.wav。九、Glama 目录提交清单glama.json 声明了维护者、许可证MIT、运行时python、标签speech-to-text、asr、audio、sensevoice、local、mcp等以及容器启动命令python /app/funasr_mcp.pyFUNASR_DEVICEcpu供 Glama 目录扫描器使用。在 Glama 平台添加服务器时应使用以下字段值字段值Docker build contextexamples/mcp_serverDockerfile pathexamples/mcp_server/DockerfileServer commandpython /app/funasr_mcp.pyExpected MCP tooltranscribe_audio提交目录 PR 前务必确认 Glama 已完成评测并给出了质量评分——仅凭 listing 或徽章接口返回 HTTP 200 并不能证明评分已生成。若徽章接口仍返回 404应暂时不把徽章放入外部目录提交直到 Glama listing 生效。十、功能特性总览五语言转录普通话、粤语、英语、日语、韩语自动检测或显式提示auto、zh、yue、en、ja、ko六种取值auto由模型自动判断语种VAD 切分长音频先由 fsmn-vad 按单段最长 30 秒切分再识别可选段落时间戳仅当配置的模型返回分句信息时才附带时间戳与说话人可配置的本地推理通过环境变量选择模型与 CPU / CUDA / MPS 设备无需 API Key完全本地推理MIT 协议隐私友好音频不离开本机。已验证的客户端兼容性工具状态Claude Code✅ 已测试Claude Desktop✅ 兼容Cursor✅ 兼容Windsurf✅ 兼容任意 MCP 客户端✅ 标准协议十一、使用注意事项路径作用域audio_path必须是 MCP 服务器进程可见的本地文件路径。容器模式下使用/audio/fileURL 和实时麦克风流不支持也不要把未挂载进容器的文件路径传给工具。首次调用较慢首次调用会下载并加载模型权重到模型缓存本机~/.cache/modelscope容器内/root/.cache/modelscope耗时明显长于后续调用工具描述中已向客户端明示这一点以便 AI 助手合理安排等待预期。输出格式约定工具返回文本中包含Transcription:前缀有段落信息时附带Segments:列表每行形如[0.0s - 3.2s] 文本模型给出说话人时会追加[Speaker 0]标记。版本一致性若自行修改 Dockerfile 中的FUNASR_VERSION或server.json中的版本号需同步更新 README 中的镜像 tag 与发布 tag否则元数据一致性测试test_registry_metadata.py会失败。FunASR MCP Server 的价值在于它以标准协议把成熟的 FunASR 语音识别栈SenseVoice fsmn-vad无缝接入到 AI 助手生态既保留了本地推理的隐私优势又让帮我转录这个音频文件这类自然语言指令成为开箱即用的能力。开发者可以在此基础上替换FUNASR_MODEL指向任意 AutoModel 兼容模型把该服务器扩展为更丰富的本地多模态工具。【免费下载链接】FunASROpen-source speech recognition toolkit for training, inference, streaming ASR, VAD, punctuation, speaker diarization pipelines, and OpenAI-compatible/MCP serving.项目地址: https://gitcode.com/GitHub_Trending/fun/FunASR创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考