Thiri Chord Intelligence — Music Theory Mcp Server

🎷 THIRI 和弦智能 — MCP 服务

让你的 AI 真正懂音乐理论。 THIRI 是面向 AI 构建者的确定性音乐理论 MCP 服务 + API，让 Claude、Cursor 或任何 MCP Agent 都能分析和弦、进行罗马数字分析、生成配音并为和弦进行重新和声，给出的是计算得出而非猜测的答案。

大模型会臆造音乐理论：错误的音符、虚假的罗马数字、无法正确进行声部进行的配音。THIRI 是一款托管 API 背后的确定性引擎（基于 ℤ/12 的音级集合理论），因此 C7sus4 会保留其挂留音，Caug 会拼写为 C E G#，而“在 Dm7 G7 Cmaj7 上使用 Coltrane changes”每次都会返回 Cmaj7 Ab7 Abmaj7 E7。

要处理 Suno / Udio 或其他生成器的输出？ 封装其输出，就能获得 Agent 值得信赖的正确和弦谱。与 tonal.js 或 music21 不同，THIRI 是托管式且原生面向 Agent 的（无需安装，支持任何语言），还能重新和声并进行声部引导，而不只是查找和弦。

⭐ 如果觉得有用，请给仓库点个星，这能帮助更多音乐人和 Agent 构建者发现它。

👥 加入 AI Music Builders：想获得更高的速率限制、创始人直接支持，以及即将推出的工具的抢先体验？加入我们的开发者社区：Skool — T.H.I.R.I. Builders。

音乐人：2 分钟完成设置（无需编写代码）

1. 在 build.thiri.ai/keys 获取免费密钥
2. 在 Claude 中：Settings → Connectors → Add custom connector → URL https://mcp.thiri.ai/mcp → 粘贴你的 sk_live_ 密钥
3. 向 Claude 提问：“用 Coltrane changes 为 Dm7 G7 Cmaj7 重新和声。”

就这么简单——无需安装，也无需配置文件。构建者可在下方查看完整安装选项（Claude Code、Desktop 配置、原始 HTTP）。

你可以这样提问

“分析 C 调中的 Dm7b5。” → iiø7、半减和弦、借用的前属和弦，+ 音阶选项 “C7sus4 中有哪些音符？” → C F G Bb（挂留音得以保留） “给我一个无根音的 Cmaj7 配音，然后声部引导到 Dm7。” → 配音 + 声部进行评分 “用 Coltrane changes 为 Dm7 G7 Cmaj7 重新和声。” → Cmaj7 Ab7 Abmaj7 E7

工具

工具	功能
analyze_chord	和弦 → 根音、性质、音程、罗马数字与和声功能（副属和弦、调式互换标签）
resolve_chord	和弦 → 拼写正确的音符、频率、MIDI、音阶建议
generate_voicing	可用于乐器演奏的配音（无根音/bill_evans、壳音、三和弦、铺底、导音、drop-2/3）；传入 previousNotes 可获得声部进行评分；使用 colorPreferences 指定扩展音
reharmonize	和弦进行重新和声——8 种技巧：tritone_sub、ii_v_insertion、modal_interchange、diminished_passing、secondary_dominant、chain_of_dominants、coltrane_changes、backdoor（或 auto）
conduct_band	用自然语言指挥乐队 → 声部轨道 + MIDI（托管 MCP v0.3+）

运行于 v2 网格引擎之上——正确处理挂留和弦、真实三和弦、等音拼写和所有变化属和弦，并提供请求超时、配额报告和结构化错误。

Conductor 与编曲配套工具（仅限桌面端）

对于 hear-it Agent 循环（指挥 → 服务端渲染 → 通过扬声器播放 WAV），请在托管理论工具旁添加第二个本地服务：

{
  "mcpServers": {
    "thiri": {
      "command": "npx",
      "args": ["-y", "@bluesprincemedia/thiri-mcp"],
      "env": { "THIRI_API_KEY": "sk_live_your_key" }
    },
    "thiri-conductor": {
      "command": "npx",
      "args": ["-y", "@bluesprincemedia/thiri-mcp", "thiri-conductor-mcp"],
      "env": { "THIRI_API_KEY": "sk_live_your_key" }
    },
    "thiri-composition": {
      "command": "npx",
      "args": ["-y", "@bluesprincemedia/thiri-mcp", "thiri-composition-mcp"]
    }
  }
}

可执行文件	工具
thiri-conductor-mcp	conduct_band、render_audio（通过 POST /v2/render 使用服务端 Csound）、play_audio、search_corpus
thiri-composition-mcp	Composition IR 工具 + play_composition（fluidsynth 预览）

自 v0.5.0 起，渲染在服务端运行——无需安装 Csound。验证：npm run test:conductor · 实时文档：build.thiri.ai/lab/conductor-mcp · Agent 配方。

Conductor Agent（氛围编曲）

用于本地氛围编曲的端到端角色——技能、CLI 和 Band 仪表盘面板：

入口	命令 / 路径
Cursor 技能	将 THIRI/lab/skills/thiri-conductor-agent/SKILL.md 复制到 ~/.cursor/skills/thiri-conductor-agent/SKILL.md
CLI	cd thiri-mcp && npm run conductor:vibe -- "gospel ballad in F minor"
仪表盘	npm run dev:studio → localhost:5173/band → Vibe Conduct 面板
实验室验证	build.thiri.ai/lab/conductor-agent

使用上面的双 MCP 配置，并在每次调用 conduct_band 后运行 mapConductResultToStudioModules。CLI 最近一次渲染会写入 ~/.thiri/conductor-last.json（仅本地，不会提交）。

旗舰 Agent 配方（分析 → 指挥 → 渲染 → 评析）

在上面的双 MCP 配置后按顺序粘贴：

1. 分析 — “使用 analyze_chord 分析调性为 C 的 Dm7 G7 Cmaj7；总结罗马数字和张力。”
2. 指挥 — “conduct_band：温暖的 Rhodes 铺底、行进贝斯、刷鼓，C 调 8 小节中速摇摆。”
3. 渲染 — “以 120 的速度从指挥结果 render_audio。”
4. 评析 — “play_audio；评析声部进行和音区平衡；提出一项修改建议。”

完整提示词：build.thiri.ai/lab/agent-recipes

托管与本地的边界

接入面	音频渲染
mcp.thiri.ai / 托管连接器	否——仅提供理论和 conduct_band 通道
本地 thiri-conductor-mcp	是——WAV 在服务端渲染（POST /v2/render），并在本地播放；无需安装 Csound

安装

在 build.thiri.ai/keys 获取免费密钥，然后选择一种方式：

Claude Desktop / Web / 移动端 — 托管（单击即可添加自定义连接器，无需安装任何内容）： Settings → Connectors → Add custom connector → URL https://mcp.thiri.ai/mcp → 在授权页面粘贴你的 sk_live_ 密钥。相同的 5 个工具、相同的密钥、相同的配额——无需配置文件，也无需 npx。

Claude Code（一行命令）：

claude mcp add thiri --env THIRI_API_KEY=sk_live_your_key -- npx -y @bluesprincemedia/thiri-mcp

Claude Desktop（claude_desktop_config.json）：

{
  "mcpServers": {
    "thiri": {
      "command": "npx",
      "args": ["-y", "@bluesprincemedia/thiri-mcp"],
      "env": { "THIRI_API_KEY": "sk_live_your_key" }
    }
  }
}

更倾向于使用原始 HTTP？（无需 MCP）

同一引擎也提供纯 REST API：

curl -X POST https://chords.thiri.ai/v2/analyze \
  -H "Authorization: Bearer YOUR_KEY" -H "content-type: application/json" \
  -d '{"chord":"Dm7b5","key":"C"}'

五个端点：/v2/analyze、/v2/resolve、/v2/voicing、/v2/reharmonize、/v2/conduct。参见 openapi.yaml。

环境变量

变量	默认值	描述
THIRI_API_KEY	（无）	Bearer 令牌（sk_live_…）——在 build.thiri.ai/keys 获取
THIRI_API_URL	https://chords.thiri.ai	API 基础地址（仅在本地开发时覆盖）

开发

npm install && npm run build && npm start

许可证

PolyForm Noncommercial 1.0.0 — © 2026 Blues Prince Media。可免费用于个人、研究和非商业用途；商业用途需获得许可 （[email protected]）。参见 LICENSE。截至 v0.5.0（含）发布的版本仍采用随附的 MIT/PolyForm 双许可证。

自 v0.5.0 起，编曲引擎和 Csound 渲染器通过托管 API 在服务端运行 （POST /v2/compose、POST /v2/render）；其源代码不再随此软件包一同发布。