内容
# Audius MCP 服务器（代码模式）
Audius MCP 服务器的代码模式允许大型语言模型（LLM）完全访问 Audius 音乐平台和开放音频协议（Open Audio Protocol）。它使用两个元工具——**搜索**和**执行**——来压缩整个 Audius API，上下文约为 1,000 个令牌。
使用 Effect-TS 构建。运行 QuickJS WASM 沙盒以实现安全代码执行。
## 工作原理
```
LLM ──► search("trending tracks") → 发现 GET /tracks/trending
──► execute("audius.request(...)") → 在沙盒中运行代码，返回结果
```
LLM 编写在隔离的沙盒中运行的 JavaScript，带有身份验证的 `audius.request()` 客户端。提示中没有 API 密钥，没有工具爆炸，没有往返开销。
## 工具
| 工具 | 功能 |
|------|-------------|
| **搜索** | 按标签、路径、方法或关键词发现 API 端点 |
| **执行** | 在 QuickJS 沙盒中运行 JavaScript 以访问 Audius API |
| **播放** | 在 Audius 桌面应用或浏览器中打开曲目 |
| **子图** | 通过 The Graph 查询链上协议数据（质押、治理、节点） |
## 快速入门
```bash
# 安装
git clone https://github.com/glassBead-tc/audius-mcp-atris.git
cd audius-mcp-atris
pnpm install
# 配置
echo 'AUDIUS_API_KEY=your_key_here' > .env
# 构建并运行
pnpm dev
```
## 获取 API 密钥
### Audius API 密钥（必需）
1. 访问 [audius.co/settings](https://audius.co/settings) 并登录（或创建帐户）
2. 滚动到 **开发者应用** 并创建新应用
3. 复制 **API 密钥** — 这将作为 `AUDIUS_API_KEY` 添加到您的 `.env` 文件中
4. 可选复制 **API 密钥** 如果您计划执行写入操作（上传、收藏）
或者，在 [api.audius.co/plans](https://api.audius.co/plans) 获取凭证。
### The Graph API 密钥（可选，用于子图工具）
子图工具查询链上协议数据（质押、治理、节点）。它需要一个 Graph API 密钥：
1. 访问 [thegraph.com/studio](https://thegraph.com/studio) 并登录
2. 创建 API 密钥（[视频教程](https://www.youtube.com/watch?v=UrfIpm-Vlgs)）
3. 将其添加到您的 `.env` 文件中作为 `GRAPH_API_KEY`
如果没有此密钥，子图工具将返回身份验证错误。所有其他工具无需此密钥即可正常工作。
## 连接到 Claude
### Claude 代码
将以下内容添加到您的项目的 `.mcp.json` 文件中：
```json
{
"mcpServers": {
"audius-mcp": {
"type": "http",
"url": "http://localhost:3000/mcp"
}
}
}
```
### Claude 桌面版
将以下内容添加到 `claude_mcp_config.json` 文件中：
```json
{
"mcpServers": {
"audius": {
"command": "node",
"args": ["/path/to/audius-mcp-atris/dist/index.js"],
"env": {
"AUDIUS_API_KEY": "your_key_here"
}
}
}
}
```
## 示例对话
**"Audius 上目前有什么流行的内容？"**
```js
// LLM 调用 search({ tag: "tracks" })，然后：
return await audius.request('GET', '/tracks/trending', { query: { limit: 5 } })
```
**"找到 deadmau5 并显示他的热门曲目"**
```js
const users = await audius.request('GET', '/users/search', { query: { query: 'deadmau5' } })
const userId = users.data[0].id
const tracks = await audius.request('GET', '/users/' + userId + '/tracks', { query: { sort: 'plays' } })
return tracks.data.map(t => ({ title: t.title, plays: t.play_count }))
```
**"协议中质押了多少 $AUDIO？"**
```graphql
{ audiusNetworks(first: 1) { totalTokensStaked totalTokensDelegated totalSupply } }
```
## 架构
```
src/
├── index.ts # 入口点 — Effect 层，HTTP 服务器
├── AppConfig.ts # 环境变量配置（AUDIUS_API_KEY，PORT）
├── mcp/
│ ├── McpSchema.ts # MCP 2025-11-25 协议（Effect Schema）
│ ├── McpSerialization.ts # JSON-RPC ↔ Effect RPC 桥接
│ ├── McpServer.ts # 请求调度（initialize，tools/*）
│ └── McpServerTransport.ts # /mcp 上的流式 HTTP
├── api/
│ ├── SpecLoader.ts # 获取并解析 Audius swagger.yaml
│ ├── SpecIndex.ts # 解析规范的搜索索引
│ └── AudiusClient.ts # 身份验证的 HTTP 客户端
├── tools/
│ ├── SearchTool.ts # 搜索工具
│ ├── ExecuteTool.ts # 执行工具
│ ├── PlayTool.ts # 播放工具
│ └── SubgraphTool.ts # 子图工具
└── sandbox/
├── Sandbox.ts # QuickJS WASM 沙盒
└── TypeGenerator.ts # 来自规范的 TS 声明
```
每个组件都是一个 Effect 服务（`Context.Tag`），通过 `Layer` 组合。沙盒使用 `QuickJSDeferredPromise` 支持无限链接的 `await` 调用。
## 环境变量
| 变量 | 必需 | 描述 |
|----------|----------|-------------|
| `AUDIUS_API_KEY` | 是 | 来自 audius.co/settings 的 API 密钥 |
| `PORT` | 否 | HTTP 服务器端口（默认：3000） |
| `GRAPH_API_KEY` | 否 | 用于子图查询的 Graph API 密钥 |
## 开发
```bash
pnpm build # 编译 TypeScript
pnpm start # 运行编译后的服务器
pnpm dev # 构建并运行
pnpm test # 运行测试
```
## 安全
- **沙盒隔离**：LLM 生成的代码在 QuickJS WASM 中运行 — 没有文件系统，没有网络，没有环境变量
- **没有原始获取**：仅 `audius.request()` 可用，硬编码为 `api.audius.co`
- **SSRF 保护**：API 路径必须以 `/` 开头，不能包含 `@`
- **内存上限**：每次执行 64MB
- **超时**：默认 30 秒，可按调用配置
- **新鲜上下文**：执行之间不会泄漏状态
## 协议
- **MCP 版本**：2025-11-25
- **传输**：`POST /mcp` 上的流式 HTTP
- **会话**：`MCP-Session-Id` 头部，内存中（无状态准备）
## 开放音频协议
此服务器基于 [开放音频协议](https://openaudio.org) 构建 — 去中心化的全球音乐数据库。Audius 是 OAP 之上的一个应用层。子图工具提供对链上协议数据的直接访问。
## 许可证
MIT
MCP 市场