grandorgue-mcp

GrandOrgue MCP

现代管风琴控制台——GrandOrgue 管风琴模拟器的免费控制界面。

GrandOrgue MCP 为 GrandOrgue 提供了美观、响应迅速的 Web 控制台，以及可供 AI Agent 使用的后端。它通过 MIDI 连接 GrandOrgue，并以现代 React 仪表板取代老旧的 wxWidgets GUI。每个音栓、活塞、键盘和渐强踏板都可以通过任意浏览器控制，也可以通过 AI Agent 使用 MCP 工具进行控制。

本项目为 GrandOrgue 社区打造，感谢数十年来免费的管风琴模拟。我们以此回馈社区——提供一个现代控制台层，可与任何现有的 GrandOrgue 安装和采样集搭配使用。

---

目录

• 快速开始
• 文档
  • README.md — 本文件，概览和快速开始
  • docs/GRANDORGUE_GUIDE.md — GrandOrgue 简介、PC 管风琴模拟的历史及 Hauptwerk 对比
  • docs/ARCHITECTURE.md — 系统架构、MIDI 桥接和端口布局
  • docs/BACH_CATALOG.md — 完整的 J.S. Bach 管风琴 MIDI 曲目
  • docs/MIDI_SETUP.md — MIDI 配置分步指南
  • docs/MCP_TOOLS.md — AI Agent 工具参考
  • docs/SAMPLE_SETS.md — 市场、免费采样集和安装指南
• 端口
• 技术栈
• 许可证

---

快速开始

前置条件

• 已安装 GrandOrgue（Windows / Linux / macOS）
• 用于管理 Python 依赖的 uv
• 用于 Web 控制台的 Node.js 20+

一键设置

# Install backend deps
just install

# Install frontend deps
just install-web

# Launch everything (backend + frontend + browser)
just web

后端将在 端口 11010（HTTP 模式）启动，前端将在 端口 11011 启动。

Claude Desktop（stdio）

服务器默认使用 stdio 传输方式，供 MCP 客户端使用。使用 just mcpb 构建打包文件，并在 Claude Desktop 中安装 dist/grandorgue-mcp-vX.Y.Z.mcpb。 Web 应用使用 HTTP 模式（MCP_TRANSPORT=http），just web 会自动设置该模式。

手动启动

# Terminal 1 — Backend
uv run grandorgue-mcp

# Terminal 2 — Frontend (opens browser)
cd web_sota && bun run dev

首次设置

1. 从 GitHub Releases 安装 GrandOrgue
2. 至少安装一个免费的采样集（参见 docs/SAMPLE_SETS.md）
3. 启动 MCP 服务（uv run grandorgue-mcp）
4. 在 http://127.0.0.1:11011 打开 Web 控制台
5. 在仪表板中点击 启动 GrandOrgue，然后点击 连接 MIDI
6. 必须将 GrandOrgue 配置为使用虚拟 MIDI 端口（参见 docs/MIDI_SETUP.md）

---

端口

端口	服务
11010	后端（HTTP 模式）— FastMCP 3.4（/mcp）+ FastAPI REST + WebSocket /ws
11011	前端 — Vite React SPA，将 /api 代理到 11010

---

技术栈

层	技术
后端	Python 3.12+、FastMCP 3.4、FastAPI、uvicorn
MIDI 桥接	mido + python-rtmidi（虚拟端口）
音频引擎	GrandOrgue C++（未修改 — 仅用于 MIDI 控制）
前端	React 18、TypeScript、Tailwind CSS、Vite（Bun）、Zustand、Lucide、react-router-dom、framer-motion、react-markdown
代码检查	Ruff（Python）、Biome（TypeScript）
测试	pytest + Playwright 端到端测试

---

许可证

MIT — 永久免费供 GrandOrgue 社区使用。