io.github.sandraschi/grandorgue-mcp
GrandOrgue pipe organ simulator MCP server - MIDI bridge, organ control, sample set management, m...
Open source Open in the app JSON README (API)
About
GrandOrgue pipe organ simulator MCP server - MIDI bridge, organ control, sample set management, m...
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- sandraschi
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.3.0
- Stars
- 2
- Last push
- 2026-08-31T10:17:59Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-29 04:01:21
- Updated
- 2026-08-29 04:01:21
- Origin id
io.github.sandraschi/grandorgue-mcp
README
# GrandOrgue MCP <p align="center"> <a href="https://github.com/sandraschi/grandorgue-mcp"><img src="https://img.shields.io/github/stars/sandraschi/grandorgue-mcp?style=flat-square" alt="Stars"></a> <a href="https://github.com/sandraschi/grandorgue-mcp/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="License"></a> <a href="https://github.com/sandraschi/grandorgue-mcp/actions/workflows/ci.yml"><img src="https://github.com/sandraschi/grandorgue-mcp/actions/workflows/ci.yml/badge.svg" alt="CI"></a> <a href="https://python.org"><img src="https://img.shields.io/badge/Python-3.12+-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python"></a> <a href="https://github.com/PrefectHQ/fastmcp"><img src="https://img.shields.io/badge/FastMCP-3.4-7c5cfc?style=flat-square" alt="FastMCP"></a> <a href="https://github.com/sandraschi/grandorgue-mcp"><img src="https://img.shields.io/badge/MIDI-bridge-009688?style=flat-square" alt="MIDI"></a> <a href="https://github.com/sandraschi/grandorgue-mcp"><img src="https://img.shields.io/badge/fleet-SOTA-6366f1?style=flat-square" alt="Fleet SOTA"></a> <a href="https://grandorgue-mcp.fleet.ai"><img src="https://img.shields.io/badge/React-18-d1d5db?style=flat-square&logo=react&logoColor=61DAFB" alt="React"></a> </p> **Modern Organ Console — a free control surface for the GrandOrgue pipe organ simulator.** GrandOrgue MCP gives GrandOrgue a beautiful, responsive web console + AI-agent-capable backend. It connects to GrandOrgue via MIDI and replaces its aging wxWidgets GUI with a modern React dashboard. Every stop, piston, manual, and swell pedal is controllable from any browser — or from an AI agent via MCP tools. Built for the GrandOrgue community with gratitude for decades of free organ simulation. This is our contribution back — a modern console layer that works with any existing GrandOrgue installation and sample set. --- ## Contents - [Quick Start](#quick-start) - [Documentation](#documentation) - [README.md](README.md) — this file, overview and quick start - [docs/GRANDORGUE_GUIDE.md](docs/GRANDORGUE_GUIDE.md) — what GrandOrgue is, history of PC organ simulation, Hauptwerk comparison - [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — system architecture, MIDI bridge, port layout - [docs/BACH_CATALOG.md](docs/BACH_CATALOG.md) — complete J.S. Bach organ MIDI repertoire - [docs/MIDI_SETUP.md](docs/MIDI_SETUP.md) — step-by-step MIDI configuration - [docs/MCP_TOOLS.md](docs/MCP_TOOLS.md) — AI agent tool reference - [docs/SAMPLE_SETS.md](docs/SAMPLE_SETS.md) — marketplace, free sample sets, installation guide - [Ports](#ports) - [Tech Stack](#tech-stack) - [License](#license) --- ## Quick Start ### Prerequisites - [GrandOrgue](https://github.com/GrandOrgue/grandorgue/releases) installed (Windows / Linux / macOS) - [uv](https://docs.astral.sh/uv/) for Python dependency management - [Node.js 20+](https://nodejs.org/) for the web console ### One-Command Setup ```powershell # Install backend deps just install # Install frontend deps just install-web # Launch everything (backend + frontend + browser) just web ``` The backend starts on **port 11010** (HTTP mode), the frontend on **port 11011**. ### Claude Desktop (stdio) The server defaults to **stdio** transport for MCP clients. Build the bundle with `just mcpb` and install `dist/grandorgue-mcp-vX.Y.Z.mcpb` in Claude Desktop. The webapp uses HTTP mode (`MCP_TRANSPORT=http`), which `just web` sets automatically. ### Manual Start ```powershell # Terminal 1 — Backend uv run grandorgue-mcp # Terminal 2 — Frontend (opens browser) cd web_sota && bun run dev ``` ### First-Time Setup 1. Install GrandOrgue from [GitHub Releases](https://github.com/GrandOrgue/grandorgue/releases) 2. Install at least one free sample set (see [docs/SAMPLE_SETS.md](docs/SAMPLE_SETS.md)) 3. Start the MCP server (`uv run grandorgue-mcp`) 4. Open the web console at http://127.0.0.1:11011 5. From the Dashboard, click **Start GrandOrgue** then **Connect MIDI** 6. GrandOrgue must be configured to use the virtual MIDI ports (see [docs/MIDI_SETUP.md](docs/MIDI_SETUP.md)) --- ## Ports | Port | Service | |------|---------| | 11010 | Backend (HTTP mode) — FastMCP 3.4 (`/mcp`) + FastAPI REST + WebSocket `/ws` | | 11011 | Frontend — Vite React SPA, proxies `/api` → 11010 | --- ## Tech Stack | Layer | Technology | |-------|-----------| | Backend | Python 3.12+, FastMCP 3.4, FastAPI, uvicorn | | MIDI Bridge | mido + python-rtmidi (virtual ports) | | Audio Engine | GrandOrgue C++ (untouched — MIDI control only) | | Frontend | React 18, TypeScript, Tailwind CSS, Vite (Bun) | | Linting | Ruff (Python), Biome (TypeScript) | | Testing | pytest + Playwright e2e | --- ## License MIT — free for the GrandOrgue community, forever.