使用说明
音轨MCP服务器
使用AI为您的业务地点提供全面的音乐管理。此MCP服务器连接 原声带 Claude、ChatGPT和任何兼容MCP的AI助手——播放控制、音乐发现、日程创建、区域分配等。
由...建造 bmasia --Soundtrack经销商。
它能做什么？
用自然语言与您的AI助手交谈：
- “大厅里现在在玩什么？”
- “将餐厅区的音量调到5”
- “搜索冷爵士播放列表” （包括预览链接）
- “制定每周时间表：爵士乐早晨、休息室晚上”
- “将该时间表分配给大厅区域”
- “排队播放下一首特定曲目”
- “显示我的所有声音区域”
- “为游泳池创建一个60首曲目的深屋播放列表，并将其放在该区域”
- “将这20首曲目添加到Lobby Evening播放列表” （编辑现有播放列表）
- “给我看看Bonobo的足迹” （艺术家和专辑目录浏览）
- “在大堂、游泳池和水疗区注册新的酒店账户” （操作员）
bmasia客户快速入门
如果您的帐户由bmasia管理，您可以使用我们的托管服务器在几分钟内连接。无需安装，无需API密钥，无需托管。
询问您的bmasia代表，他们会给您发送 服务器网址 和你的 帐户ID.更换 YOUR_SERVER 和 YOUR_ACCOUNT_ID 在下面的例子中。
克劳德桌面版
编辑您的配置文件：
- macOS：
~/Library/Application Support/Claude/claude_desktop_config.json - 窗户：
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"soundtrack": {
"type": "url",
"url": "https://YOUR_SERVER/c/YOUR_ACCOUNT_ID/mcp"
}
}
}
重新启动克劳德桌面。您将在连接器中看到“配乐”。
Claude.ai（网络和移动）
- 首选 claude.ai > 设置 > 连接器
- 点击 添加自定义连接器
- 输入URL：
https://YOUR_SERVER/c/YOUR_ACCOUNT_ID/mcp - 点击 添加 --OAuth将自动完成
- 开始新的聊天并尝试： “现在在玩什么？”
ChatGPT
- 首选 chatgpt.com > 设置 > 应用
- 启用 开发人员模式 （需要ChatGPT Plus）
- 点击 添加连接器 并输入URL：
https://YOUR_SERVER/c/YOUR_ACCOUNT_ID/mcp - OAuth将自动完成
- 开始新的聊天并尝试： “显示我的声音区域”
多个账户
如果您管理多个帐户，请用逗号分隔：
https://YOUR_SERVER/c/ACCOUNT_ID_1,ACCOUNT_ID_2/mcp
帐户隔离
每个作用域的URL只能访问指定的帐户。酒店A看不到酒店B的数据——他们每个人都有自己的URL和自己的帐户ID。
自助主机（适用于非bmasia用户）
如果你 不 作为bmasia客户，您需要自己的Soundtrack API证书和自己的服务器。托管的bmasia服务器使用bmasia的API密钥，该密钥仅适用于bmasia-managed帐户。
1.获取API证书
在申请API访问权限 soundtrack.io/our-api/apply。您将收到客户端ID和客户端密码。
创建base64编码的令牌：
echo -n "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" | base64
2.克隆并安装
git clone https://github.com/brightears/soundtrack-mcp.git
cd soundtrack-mcp
npm install
3.配置
cp .env.example .env
编辑 .env 并添加您的base64编码令牌：
SOUNDTRACK_API_TOKEN=your_base64_encoded_token_here
4.建造
npm run build
5.连接到克劳德桌面（本地）
编辑您的配置：
- macOS：
~/Library/Application Support/Claude/claude_desktop_config.json - 窗户：
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"soundtrack": {
"command": "node",
"args": ["/full/path/to/soundtrack-mcp/dist/index.js"],
"env": {
"SOUNDTRACK_API_TOKEN": "your_base64_encoded_token_here"
}
}
}
}
重新启动克劳德桌面。
6.部署为HTTP服务器（用于网络/移动访问）
要与Claude.ai、ChatGPT或任何远程MCP客户端一起使用，请部署HTTP服务器：
npm run start:http
从端口3000开始（或 PORT env变量）。该服务器包括Claude.ai和ChatGPT所需的内置OAuth 2.1支持。
| 端点 | 与一起使用 |
|---|---|
/mcp |
Claude.ai、ChatGPT、MCP客户端 |
/api/* |
REST API |
/openapi.json |
OpenAPI规范 |
/c/{accountIds}/mcp |
MCP范围（每个客户） |
/c/{accountIds}/api/* |
范围REST（每个客户端） |
/health |
健康检查 |
部署到Render、Railway、Fly.io或任何Node.js主机。集 SOUNDTRACK_API_TOKEN 作为环境变量。
部署后，使用服务器的URL将其添加为Claude.ai或ChatGPT中的连接器（例如。 https://your-server.com/mcp).
7.（可选）特定账户的范围
有两种方法可以限制哪些帐户可见：
通过URL路径 （适用于多客户端设置）：
https://your-server.com/c/ACCOUNT_ID_1,ACCOUNT_ID_2/mcp
通过环境变量 （适用于单客户端设置）：
SOUNDTRACK_ACCOUNT_IDS=ACCOUNT_ID_1,ACCOUNT_ID_2
角色和权限
两个连接角色，由HTTP端点+ OPERATOR_TOKEN env 是：
- 客户 —
/c/<account_ids>/mcp。仅限于URL中的帐户ID。除subscription_activate和account_register。不触发计费。 - 操作员 —
/operator/mcp（或/mcp随着X-Operator-Token头球完全访问服务器的API令牌可以看到的所有帐户。所有可用的工具，包括影响成本的工具。
当 OPERATOR_TOKEN 未设置（自托管/单用户安装），每个端点默认为operator，门为no-op。
对于多租户部署（例如BMAsia托管客户端），设置 OPERATOR_TOKEN 在服务器上，分发 /c/<ids>/mcp URL指向客户端，并将运算符URL+令牌保持在内部。
作用域别名
否则，拥有多个帐户的客户（例如，拥有250多家酒店的连锁酒店）需要每个帐户ID都有一个7KB以上的URL。通过定义短别名 SCOPE_ALIASES env-var（JSON映射），这样他们就可以得到一个干净的URL，比如 /c/tui/mcp:
# On the server (e.g. Render env vars)
SCOPE_ALIASES='{"tui":"id1,id2,id3,...","other-chain":"id4,id5"}'
然后，客户通过以下方式连接：
https://your-server/c/tui/mcp
别名解析为服务器端的完整帐户ID列表。如果路径段不是已知别名，则将其视为原始逗号分隔列表（向后兼容）。
获取 /scope-aliases 返回操作调试的名称+每个别名帐户计数（不公开ID）。
可用工具（41）
发现
| 工具 | 说明 |
|---|---|
list_accounts |
列出所有帐户 |
search_account |
按企业名称搜索帐户 |
list_locations |
列出帐户的位置 |
list_sound_zones |
列出具有配对状态的声音区域 |
get_account_overview |
完整帐户/位置/区域树 |
回放控制
| 工具 | 说明 |
|---|---|
get_now_playing |
声音区域中的当前曲目 |
set_volume |
设置音量（通常为0-16） |
skip_track |
跳到下一首曲目 |
play |
恢复播放 |
pause |
暂停播放 |
图书馆与音乐探索
| 工具 | 说明 |
|---|---|
list_playlists |
在帐户的音乐库中列出播放列表 |
list_schedules |
在帐户的音乐库中列出时间表 |
search_music |
搜索Soundtrack目录（播放列表、曲目、艺术家、专辑） |
browse_categories |
浏览带有精选播放列表的音乐类别 |
get_playlist_tracks |
查看播放列表中的曲目 |
进度管理
| 工具 | 说明 |
|---|---|
create_schedule |
创建带有时间段的音乐时间表（支持每日/工作日/周末/自定义日） |
update_schedule |
更新现有计划（替换所有插槽） |
get_schedule_details |
查看日程表中的时间段 |
区域分配
| 工具 | 说明 |
|---|---|
assign_source |
将日程表或播放列表分配给一个或多个区域 |
get_zone_source |
查看分配给区域的日程表/播放列表 |
内容管理
| 工具 | 说明 |
|---|---|
create_playlist |
创建自定义手动播放列表，可选择包含曲目 |
queue_tracks |
在某个区域中排队播放特定曲目 |
block_track |
阻止在区域内播放曲目 |
add_to_library |
将播放列表或日程添加到帐户的库中 |
remove_from_library |
从帐户库中删除播放列表或计划 |
AI功能
| 工具 | 说明 |
|---|---|
generate_playlist |
使用Soundtrack的AI从文本描述生成播放列表 |
管理员--帐户/位置/区域生命周期
| 工具 | 描述 | 角色 |
|---|---|---|
account_register |
创建一个新的SYB帐户（计划、国家、地址、所有者user_id）。 | 操作员 |
account_add_user |
在帐户上添加一个用户（通过电子邮件）作为管理员/所有者/联系人等。 | 两者都有 |
location_create |
在帐户下创建一个位置。可选的 sound_zone_name 在一次呼叫中播种第一个区域。 |
两者都有 |
location_update |
重命名位置。 | 两者都有 |
location_delete |
删除位置（必须没有活动区域）。 | 两者都有 |
sound_zone_create |
在某个位置下创建分区。惰化至 subscription_activate。 |
两者都有 |
sound_zone_update_name |
重命名一个区域——用于镜像外部真实来源（例如客户的姓名或定价表）。 | 两者都有 |
sound_zone_delete |
删除区域（如果激活，请先取消订阅）。 | 两者都有 |
sound_zone_initiate_pairing |
为未配对区域生成配对代码。 | 两者都有 |
sound_zone_unpair |
打开某个区域上的设备（启动当前播放，直到重新配对）。 | 两者都有 |
管理员--订阅生命周期
| 工具 | 描述 | 角色 |
|---|---|---|
subscription_activate |
激活区域上的订阅。 仅限操作员 --触发SYB计费至少一个月。 | 操作员 |
subscription_cancel |
取消某个区域的订阅（该区域将一直播放到计费期结束）。 | 两者都有 |
管理员--验证
| 工具 | 描述 | 角色 |
|---|---|---|
account_billing_status |
帐户的权威订阅状态：活动流订阅计数、计费日期、按状态划分的区域。“我的激活是否生效”的真相来源——区域级订阅字段可能已经过时。 | 两者都有 |
sound_zone_full_state |
单区域完整状态：已配对、在线、订阅、当前来源。在处理客户“请回复”请求之前使用。 | 两者都有 |
sound_zone_playback_history |
最后播放的N首曲目+源代码。区分音乐设计问题（错误曲目）和设备问题（根本无法播放）。 | 两者都有 |
建筑
src/
client.ts GraphQL client + auth
queries.ts GraphQL queries & mutations
tools.ts MCP tool definitions (shared)
auth.ts OAuth 2.1 provider (auto-approving)
index.ts stdio entry point (Claude Desktop)
http.ts HTTP entry point (Claude.ai / ChatGPT / remote)
api.ts REST API router
内置：
- 模型上下文协议SDK v1.26
- 配乐GraphQL API
- TypeScript、Express、Zod
发展
npm run dev # Watch mode (auto-recompile)
npm run build # One-time compile
npm run inspect # MCP Inspector (test tools interactively)
许可证
麻省理工学院
