Mcp Audio Server

MCP Audio Server

一个独立的 MCP Audio Server 示例项目，提供音乐搜索与分页音频读取能力。

这个项目从 xiaozhi-esp32-server-golang/examples/mcp_audio 中拆出，整理成了一个可单独运行的 Go 项目，适合直接测试，也适合作为你自己的音频类 MCP Server 模板。

功能

• 提供 musicPlayer 工具
• 通过 ResourceLink 返回可播放音频资源
• 通过 resource/read 分页读取音频数据
• 返回 BlobResourceContents，其中 Blob 为 base64 编码
• 支持 stdio 与 Streamable HTTP 两种传输方式

工具与资源

Tool: musicPlayer

入参：

{
  "query": "周杰伦"
}

返回：

• ResourceLink.URI: resource://read_from_http
• ResourceLink.Name: 实际歌曲名
• ResourceLink.Description: 实际音频 URL
• ResourceLink.MIMEType: audio/mpeg

Resource: resource://read_from_http

通过 resource/read 分页读取音频内容，参数放在 Arguments 中：

{
  "url": "https://example.com/audio.mp3",
  "start": 0,
  "end": 102400
}

返回内容是 BlobResourceContents：

• MIMEType: audio/mpeg
• Blob: base64 编码后的音频二进制

当服务端返回空数据时，会改为返回 base64 编码后的 [DONE]，作为流结束标记。

环境要求

• Go 1.24+
• 可访问外部音乐搜索与音频链接

安装依赖

go mod tidy

运行

1. stdio 模式

默认就是 stdio：

go run .

2. HTTP 模式

go run . -t http

或：

go run . --transport http

HTTP 模式下：

• 监听端口：3001
• MCP 路径：/mcp
• 完整地址：http://localhost:3001/mcp

调用流程

1. 客户端调用 musicPlayer
2. 服务端搜索歌曲并返回 ResourceLink
3. 客户端根据 ResourceLink.URI 发起 resource/read
4. 客户端在 Arguments 中传入 url、start、end
5. 服务端返回 base64 编码的 BlobResourceContents
6. 客户端解码后边读边播，直到收到 [DONE]

快速测试

启动 HTTP 模式后，可以用支持 MCP 的客户端连接 http://localhost:3001/mcp。

如果你只是本地验证构建是否正常：

go build .

注意事项

• 当前歌曲搜索依赖 github.com/scroot/music-sd
• 搜索结果和真实音频链接依赖外部站点能力，稳定性受外部服务影响
• 这个仓库更适合作为音频类 MCP Tool 的接入模板；如果你要接入自己的音频源，建议保留下面这些协议约定：

Tool -> ResourceLink -> resource/read(Arguments 分页) -> Blob(base64) -> [DONE]

项目结构

.
├── LICENSE
├── README.md
├── go.mod
├── go.sum
└── main.go

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: hackers365
• Source: hackers365/mcpaudio_server
• License: MIT

Install and usage instructions live in the source repository linked above.