# grandorgue-mcp [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/sandraschi/grandorgue-mcp  
**GitHub Stars:** 2  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/grandorgue-mcp

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

## Claude Desktop Quick Installation
Heuristic fallback — verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low):

```json
"mcpServers": {
  "grandorgue-mcp": {
    "command": "npx",
    "args": ["-y","grandorgue-mcp"]
  }
}
```

## Documentation & 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](https://github.com/sandraschi/grandorgue-mcp/blob/HEAD/README.md) — this file, overview and quick start
  - [docs/GRANDORGUE_GUIDE.md](https://github.com/sandraschi/grandorgue-mcp/blob/HEAD/docs/GRANDORGUE_GUIDE.md) — what GrandOrgue is, history of PC organ simulation, Hauptwerk comparison
  - [docs/ARCHITECTURE.md](https://github.com/sandraschi/grandorgue-mcp/blob/HEAD/docs/ARCHITECTURE.md) — system architecture, MIDI bridge, port layout
  - [docs/BACH_CATALOG.md](https://github.com/sandraschi/grandorgue-mcp/blob/HEAD/docs/BACH_CATALOG.md) — complete J.S. Bach organ MIDI repertoire
  - [docs/MIDI_SETUP.md](https://github.com/sandraschi/grandorgue-mcp/blob/HEAD/docs/MIDI_SETUP.md) — step-by-step MIDI configuration
  - [docs/MCP_TOOLS.md](https://github.com/sandraschi/grandorgue-mcp/blob/HEAD/docs/MCP_TOOLS.md) — AI agent tool reference
  - [docs/SAMPLE_SETS.md](https://github.com/sandraschi/grandorgue-mcp/blob/HEAD/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](https://github.com/sandraschi/grandorgue-mcp/blob/HEAD/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](https://github.com/sandraschi/grandorgue-mcp/blob/HEAD/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.