MCP Music Studio

A creative music tool for AI systems — compose, arrange, and play music with multi-instrument audio, style presets, and visual sheet music.

Forked from @modelcontextprotocol/server-sheet-music and substantially extended.

Features

• 8 style presets — rock, jazz, bossa, waltz, march, reggae, folk, classical. One parameter adds drums + bass + chord accompaniment.
• 30 instruments — selectable from UI or via tool parameter, with fuzzy matching
• Three rendering modes — ext-apps inline UI for Claude Desktop/VS Code, browser fallback for CLI environments, configurable via --render-mode
• get-music-guide tool — on-demand reference for AI systems (instruments, drums, ABC syntax, arrangements, genre templates, MIDI directives)
• 7 music://guide/* resources — same content for resource-capable clients
• Note highlighting — currently playing notes light up during playback
• Forgiving parser — warnings don't block playback, only fatal errors do
• Streaming render — sheet music appears as the AI types (ontoolinputpartial)
• Tempo slider — warp control in the UI
• Fullscreen mode — via ext-apps requestDisplayMode

Install

Requires Node.js 18+. Supports stdio and HTTP transports.

CLI Install (one-liner)

# Claude Code
claude mcp add music-studio -- npx -y mcp-music-studio --stdio

# Codex CLI
codex mcp add -- npx -y mcp-music-studio --stdio

# Gemini CLI
gemini mcp add -- npx -y mcp-music-studio --stdio

Claude Desktop

Config file location:

| OS | Path | |----|------| | macOS | ~/Library/Application Support/Claude/claude_desktop_config.json | | Windows | %APPDATA%\Claude\claude_desktop_config.json | | Linux | ~/.config/Claude/claude_desktop_config.json |

{
  "mcpServers": {
    "music-studio": {
      "command": "npx",
      "args": ["-y", "mcp-music-studio", "--stdio"]
    }
  }
}

VS Code

Add to .vscode/mcp.json (project) or user settings:

Note: VS Code uses "servers" not "mcpServers". Also works in Trae, Void, and PearAI.

{
  "servers": {
    "music-studio": {
      "command": "npx",
      "args": ["-y", "mcp-music-studio", "--stdio"]
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project):

{
  "mcpServers": {
    "music-studio": {
      "command": "npx",
      "args": ["-y", "mcp-music-studio", "--stdio"]
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "music-studio": {
      "command": "npx",
      "args": ["-y", "mcp-music-studio", "--stdio"]
    }
  }
}

Windows

On Windows, npx is a .cmd file and requires a shell wrapper:

{
  "mcpServers": {
    "music-studio": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "mcp-music-studio", "--stdio"]
    }
  }
}

ChatGPT

ChatGPT only supports remote HTTPS MCP servers. Run the HTTP transport and expose via tunnel:

npx mcp-music-studio
# Server starts on http://localhost:3001/mcp
# Use ngrok, Cloudflare Tunnel, etc. to expose publicly

HTTP Transport

npx mcp-music-studio
# Server starts on http://localhost:3001/mcp

Tools

play-sheet-music

Creates and plays music with visual sheet music and multi-instrument audio.

| Parameter | Type | Description | |-----------|------|-------------| | abcNotation | string | ABC notation with optional chord symbols | | instrument | string? | Default instrument (e.g., "Violin", "Flute") | | style | enum? | Accompaniment style: rock, jazz, bossa, waltz, march, reggae, folk, classical | | tempo | number? | BPM (40-240) | | swing | number? | Swing feel (0-100) | | transpose | number? | Semitones (-12 to 12) |

Example — jazz arrangement:

{
  "abcNotation": "X:1\nT:Blue Note\nM:4/4\nL:1/8\nK:Bb\n\"Bbmaj7\"d2 f2 d2 Bc | \"Eb7\"_e2 g2 e2 cB | \"Dm7\"d2 f2 a2 fd | \"G7\"g2 f2 e2 dc |",
  "style": "jazz",
  "instrument": "Alto Sax",
  "tempo": 140
}

get-music-guide

Returns reference material for composition. Topics:

| Topic | Contents | |-------|----------| | instruments | All 128 GM instruments by family, program numbers, combo suggestions | | drums | Percussion notes, pattern syntax, 8 ready-to-use patterns | | abc-syntax | Notes, rests, chords, repeats, dynamics, multi-voice, lyrics | | arrangements | Multi-voice patterns, volume balancing, accompaniment setup | | genres | Complete ABC examples: jazz, blues, folk, minuet, rock, bossa, lullaby | | styles | What each style preset does and when to use it | | midi-directives | Full %%MIDI reference for ABCJS |

Render Modes

The server auto-detects whether the client supports ext-apps UI. For clients that don't, use --render-mode to control how music is delivered:

| Mode | Flag | Behavior | |------|------|----------| | auto | (default) | Inline ext-apps UI for Claude Desktop, VS Code | | browser | --render-mode browser | Saves HTML player and opens in system browser | | html | --render-mode html | Returns HTML as embedded resource in response |

Use --output-dir to control where HTML player files are saved (default: ~/Desktop/mcp-music-studio).

Example — Cherry Studio, CLI environments, or other non-ext-apps clients:

{
  "mcpServers": {
    "music-studio": {
      "command": "npx",
      "args": ["-y", "mcp-music-studio", "--stdio", "--render-mode", "browser", "--output-dir", "/path/to/output"]
    }
  }
}

Development

bun install
bun run dev      # watch + serve (hot reload)
bun run build    # production build
bun run serve    # HTTP server on port 3001

Architecture

mcp-music-studio/
├── server.ts              # MCP server: tools, resources, guides, forgiving parser
├── main.ts                # Entry point: HTTP + stdio transports
├── mcp-app.html           # HTML shell (Vite inlines everything for ext-apps UI)
├── src/
│   ├── mcp-app.ts         # Ext-apps client: rendering, audio, streaming
│   ├── mcp-app.css        # Styles: dark mode, note highlighting, toolbar
│   ├── music-logic.ts     # Shared: instruments, presets, ABC processing
│   ├── server-logic.ts    # Server: parse validation, result construction
│   ├── browser-fallback.ts # Browser player: HTML generation, auto-open
│   └── global.css         # Base reset
├── tests/                 # Vitest tests
├── vite.config.ts         # Single-file HTML bundling
├── tsconfig.json          # Client TypeScript config
└── tsconfig.server.json   # Server TypeScript config

Attribution

This project is a fork of the Sheet Music Server example from the MCP ext-apps repository by Anthropic, licensed under MIT.

License

MIT