io.github.sandraschi/grandorgue-mcp

Official

by sandraschi · TypeScript

GrandOrgue pipe organ simulator MCP server - MIDI bridge, organ control, sample set management, m...

GrandOrgue MCP Server

The io.github.sandraschi/grandorgue-mcp server is a GrandOrgue pipe organ simulator MCP server. It provides an integration layer for MIDI bridging and organ control, along with sample set management capabilities. It is distributed under the MIT license and includes CI configuration for automated workflows.

🛠️ Key Features

MIDI bridge for connecting MIDI to the simulator
Organ control functionality
Sample set management

🚀 Use Cases

Drive a GrandOrgue pipe organ simulator via MIDI input
Manage and apply organ-related sample sets
Integrate organ simulation control into MCP-based toolchains

⚡ Developer Benefits

Exposes capabilities through the MCP server model
Supports developer workflows via included CI configuration
Clearly categorized by topics such as mcp, midi, and pipe-organ

⚠️ Limitations

The provided metadata does not specify available tool names/count or protocol method details.

Topics

fastmcpfleetgrandorguemcpmidiorganpipe-organreact

README.md5 KBView on GitHub

GrandOrgue MCP

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.

Quick Start
Documentation
- README.md — this file, overview and quick start
- docs/GRANDORGUE_GUIDE.md — what GrandOrgue is, history of PC organ simulation, Hauptwerk comparison
- docs/ARCHITECTURE.md — system architecture, MIDI bridge, port layout
- docs/BACH_CATALOG.md — complete J.S. Bach organ MIDI repertoire
- docs/MIDI_SETUP.md — step-by-step MIDI configuration
- docs/MCP_TOOLS.md — AI agent tool reference
- docs/SAMPLE_SETS.md — marketplace, free sample sets, installation guide
Ports
Tech Stack
License

Quick Start

Prerequisites

GrandOrgue installed (Windows / Linux / macOS)
uv for Python dependency management
Node.js 20+ 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

Install GrandOrgue from GitHub Releases
Install at least one free sample set (see docs/SAMPLE_SETS.md)
Start the MCP server (uv run grandorgue-mcp)
Open the web console at http://127.0.0.1:11011
From the Dashboard, click Start GrandOrgue then Connect MIDI
GrandOrgue must be configured to use the virtual MIDI ports (see 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), Zustand, Lucide, react-router-dom, framer-motion, react-markdown
Linting	Ruff (Python), Biome (TypeScript)
Testing	pytest + Playwright e2e

License

MIT — free for the GrandOrgue community, forever.

Install

mcpb

shell

mcpb: https://github.com/sandraschi/grandorgue-mcp/releases/download/v0.3.0/grandorgue-mcp-v0.3.0.mcpb