如何把 FunASR 配置为 MCP 服务器让 Claude 与 Cursor 转写本地音频【免费下载链接】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如果你想在 Claude 或 Cursor 里直接让 AI 助手转写机器上的本地音频文件又不想把音频传给云端 APIFunASR 提供了一个基于 Model Context Protocol。配置完成后助手会获得一个名为transcribe_audio的工具调用时在本机完成推理音频不离开你的机器也不需要任何 API key。默认模型是iic/SenseVoiceSmall支持普通话、粤语、英语、日语、韩语的自动检测或显式指定。本文覆盖两条路径直接在 Python 环境中运行脚本主路径以及用 Docker 容器运行可选分支。两条路径的服务协议相同——MCP 客户端通过 stdio 启动它而不是 HTTP。1. 准备环境与服务器脚本funasr_mcp.py位于仓库的examples/mcp_server/目录下而 PyPI 安装的funasr包不包含仓库的examples/目录所以无论哪条路径你都需要一份仓库 checkout 来提供脚本。在已安装 Python 3.11 的机器上准备环境Agent 集成文档使用同一套准备方式git clone https://gitcode.com/GitHub_Trending/fun/FunASR.git FunASR-agent cd FunASR-agent python3.11 -m venv .venv source .venv/bin/activate python -m pip install funasrmcp_server 说明文档给出的依赖安装命令就是pip install funasr这个脚本不需要额外的 MCP SDK 包。如果你希望直接使用当前 checkout 的源码而不是 PyPI 上的发布版本按安装指南改为python -m pip install -e .并记录对应的 commit。准备完成后脚本入口是仓库根目录下的python examples/mcp_server/funasr_mcp.py注意这条命令用于理解服务如何启动实际使用时不需要手动运行它——MCP 客户端Claude、Cursor会通过 stdio 自动拉起这个脚本并管理其生命周期。2. 配置 MCP 客户端按你使用的工具选择对应配置。文档给出的配置示例中/path/to开头的路径都指你的 FunASR checkout 的绝对路径首次配置时需要整体替换。Claude Code~/.claude.json{ mcpServers: { funasr: { command: python, args: [/path/to/examples/mcp_server/funasr_mcp.py], env: {FUNASR_DEVICE: cuda} } } }Claude Desktopclaude_desktop_config.json{ mcpServers: { funasr: { command: python, args: [/path/to/funasr_mcp.py], env: {FUNASR_DEVICE: cpu} } } }CursorSettings → MCP Servers → AddCommand:python /path/to/funasr_mcp.pyEnvironment:FUNASR_DEVICEcuda上面的FUNASR_DEVICE值cuda/cpu是文档示例中各工具的示例取值按你本机实际可用的加速器选择cuda、cpu或mps不设置时默认cpu。如果你的 funasr 装在虚拟环境里裸python命令可能指向系统解释器导致 import 失败。Agent 集成文档 建议改用绝对路径指向准备好的 Python 环境和 checkout{ mcpServers: { funasr: { command: /path/to/FunASR-agent/.venv/bin/python, args: [/path/to/FunASR-agent/examples/mcp_server/funasr_mcp.py], env: { FUNASR_DEVICE: cpu, FUNASR_MODEL: iic/SenseVoiceSmall } } } }这里/path/to/FunASR-agent替换为你第 1 步 checkout 的目录。环境变量变量默认值说明FUNASR_DEVICEcpu推理设备cuda、cpu或mpsFUNASR_MODELiic/SenseVoiceSmall传给AutoModel的模型名或本地模型路径3. 工具参数与调用方式服务器只暴露一个工具transcribe_audio把音频文件转写成文本参数类型必填说明audio_pathstring是音频文件路径wav、mp3、flac、m4a、ogg必须是服务器进程可见的本地文件languagestring否auto、zh、yue、en、ja、ko默认auto返回值是转写文本如果模型返回了分段信息还会附带各分段的起止时间秒和文本。顶层结果中的富文本标签会被脚本去掉。配置完成后直接用自然语言让助手干活例如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.m4a4. 验证配置是否生效文档明确提醒只完成安装或 MCP 握手并不能证明模型真的能跑真正有效的验证是一次真实的转写请求。向助手发起第 3 节那样的请求后判断依据是成功时助手收到Transcription: ...开头的文本有分段时后跟Segments:与每段的时间区间首次调用可能会先下载并加载模型权重响应比后续调用慢这属于文档说明的正常现象不是错误失败时脚本会返回明确的错误文本可以据此定位file not found: 路径——路径对服务器进程不可见。注意audio_path只接受本地文件不接受 URL 和实时麦克风流unsupported language 值; choose one of: auto, zh, yue, en, ja, ko——语言提示超出支持列表transcription failed: 具体异常——转写本身出错需要结合异常信息检查设备与依赖环境。使用 Docker 路径时还可在不下载模型的情况下验证镜像入口与 MCP 握手是否工作python examples/mcp_server/smoke_test.py funasr-mcp该命令对容器执行initialize和tools/list两个握手请求确认serverInfo.name为funasr、工具列表包含transcribe_audio通过后输出MCP container smoke test passed: funasr-mcp。它只验证握手不等价于一次成功转写。5. 可选分支用 Docker 运行如果不想在本机装 Python 依赖可以用仓库自带的 Dockerfile 构建镜像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两个挂载是这条命令的关键src/path/to/audio替换为你本机存放音频的目录容器内以只读方式挂在/audio第二个 volume 把 ModelScope 下载的模型文件持久化到/root/.cache/modelscope避免每次运行重新下载。容器场景下传给工具的audio_path必须写成/audio/之下的路径例如/audio/meeting.wav主机上的原路径在容器内不可见。仓库也发布了固定版本的官方镜像server.json 中声明的元数据版本0.1.2对应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客户端配置方式与第 2 节一致只是把启动命令换成docker run对应的镜像调用。6. 限制与已知边界文件访问不是授权边界本地工具不会替你隔离文件系统权限助手和服务器能读到哪些文件由挂载/路径决定需要自行控制。换模型不改变工具契约设置FUNASR_MODEL指向其他模型不会改变transcribe_audio的参数结构文档也不保证其他模型与其 VAD 路径兼容。语言列表固定语言提示只支持auto、zh、yue、en、ja、ko六项不支持的其他语言代码会直接报错。客户端兼容情况来自 mcp_server READMEClaude Code 已实测TestedClaude Desktop、Cursor、Windsurf 标记为 Compatible任意标准 MCP 客户端均可通过协议接入。首次调用需要联网下载模型权重离线使用时需按安装指南预先准备好完整模型目录再把FUNASR_MODEL指向本地目录。更多细节可参考 examples/mcp_server/README.md 与 docs/agent_integration.md 的 MCP server 章节。【免费下载链接】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），仅供参考