nobu

Game-agnostic MCP toolkit for composing chiptune / retro MIDI and rendering game audio.

Plug nobu into Cursor, Claude Desktop, or Kilo Code. Ask an agent to compose a stage theme — get a real multi-track .mid, then render to .ogg / .wav for your engine.

nobu ships no game-specific data. Your project supplies tonic, mood, and biome params.

  agent / examples ──► nobu MCP ──► assets/midi/{project}.mid
                                      │
  assets/soundfonts/*.sf2 ──┐         ▼
                            └─► render MCP / scripts ──► output/audio/{project}/wav|ogg/

Agent-ready?

Cursor / Claude Code / Kilo (opened on this repo): yes — after clone the agent should read AGENTS.md / CLAUDE.md, run python scripts/bootstrap.py --no-prompt, reload MCP, and be ready. Humans can run python scripts/bootstrap.py without flags for an interactive optional-upgrade menu. Rules/skills ship in-repo (.cursor/rules, .claude/skills); MCP/Kilo configs are generated locally by bootstrap (templates: .mcp.example.json, .kilo/kilo.example.jsonc).

Cursor caveat: new project MCP servers start disabled (Cursor security). After bootstrap + reload, toggle nobu on once under Settings → MCP (or Customize → MCP). Stays on for that workspace afterward — we cannot force-enable from the repo.

Claude Desktop: almost — same bootstrap, but the agent must also merge the MCP snippet into the global claude_desktop_config.json (Desktop does not auto-load project .mcp.json).

Not magic: python must be on PATH; open the cloned folder; reload after bootstrap; on Cursor, enable nobu once if it appears disabled.

Related MCP server: cochlea

Paste this to your agent

Clone https://github.com/francescojr/nobu.git (sibling folder or into this workspace).
Read AGENTS.md (and CLAUDE.md if present) and run: python scripts/bootstrap.py --no-prompt
If this is a game project, also run: python scripts/bootstrap.py --integrate <this_project_root> --no-prompt
Reload MCP. In Cursor, enable server "nobu" if it is disabled (Settings → MCP).
Confirm tools: compose (start_project … export_midi) + Mega Drive (export_megadrive) + render (render_project / render_all_modes).
Then follow .claude/skills/game-music-producer/ — deliver MIDI, audio, and/or VGM when I ask.

Integrating into an existing game:

Set up https://github.com/francescojr/nobu as our game-music MCP.
Clone it next to this repo, run python scripts/bootstrap.py --integrate <absolute path to this project> --no-prompt,
reload MCP, and confirm tools work. Do not hardcode our game data into nobu.

Agents follow AGENTS.md. Bootstrap rewrites project-local .cursor/mcp.json + .mcp.json + .kilo/kilo.jsonc to the local venv (never global Cursor MCP).

Fastest path to sound

Human (interactive menu for optional upgrades):

git clone https://github.com/francescojr/nobu.git
cd nobu
python scripts/bootstrap.py
# → optional menu for tinysoundfont / FluidSynth / ffmpeg hints
# → reload Cursor/Kilo → enable nobu once → ask your agent for music

Agent / CI (no prompts):

python scripts/bootstrap.py --no-prompt

Prove audio works (no MCP):

python scripts/bootstrap.py --no-prompt --smoke

Optional upgrades later:

python scripts/bootstrap.py --with-render --no-prompt   # hybrid drums (pip)
python scripts/bootstrap.py --doctor                    # re-check deps
# SF2: copy your .sf2 → assets/soundfonts/default.sf2 (see assets/soundfonts/README.md)
# Kilo: Settings → MCP → nobu → Network Timeout → 5 min

Works out of the box vs optional

Quick start (manual)

git clone https://github.com/francescojr/nobu.git
cd nobu
python scripts/bootstrap.py
# creates .venv, installs deps, writes .cursor/mcp.json, optional upgrade menu

Then reload MCP. In Cursor: Settings → MCP → enable nobu once if disabled. Full notes: SETUP.md.

Demo without MCP

python examples/demo_biome_ost.py
python scripts/render_midi.py --mode chip   # always works, no SF2 needed
# → assets/midi/*.mid  and  output/audio/{project}/wav|ogg/

Render modes (chip / hybrid / full SF2)

Full SF2 always does FluidSynth → WAV, then converts to OGG (prefer ffmpeg on Windows). FluidSynth is not asked to write OGG directly.

python scripts/render_midi.py --mode chip
python scripts/render_midi.py --mode sf2 --soundfont assets/soundfonts/default.sf2
python scripts/render_track.py assets/midi/biome1_calm.mid --mode hybrid

Folder layout

Env overrides: NOBU_MIDI_DIR, NOBU_OUTPUT_DIR, NOBU_SF2 (also FLUID_SYNTH_SF2).

MCP tools

Audio output: output/audio/{project}/wav/ and .../ogg/. Mega Drive: .../vgm/.

Mood keys: safe_exploration, heroic_exploration, nostalgic_town, melancholic_dungeon, hostile_exotic_biome, magical_dreamlike, combat, victory, classic_retro.

SoundFonts

Place your own .sf2 at:

assets/soundfonts/default.sf2

Or set NOBU_SF2=/path/to/yours.sf2. Re-check: python scripts/bootstrap.py --doctor or MCP get_render_capabilities.

Without a soundfont, chip render always works via the built-in NES-style synth. Hybrid/sf2 modes fall back to chip until you add a soundfont.

Mega Drive / VGM (SGDK)

Export a console-ready VGM after compose:

python scripts/export_megadrive.py assets/midi/my_track.mid --json
# → output/audio/my_track/vgm/my_track.vgm

MCP: get_megadrive_capabilities → export_megadrive("my_track").

Builtin FM patches + PSG noise drums always work. Optional BYO patches/PCM live under assets/megadrive/ (not shipped — same policy as SoundFonts). See assets/megadrive/README.md. Point your SGDK .res at the VGM (XGM name "file.vgm"); rescomp runs xgmtool in the game project.

Agent skill

Copy or open this repo so Cursor / Claude can load:

.claude/skills/game-music-producer/

When the nobu MCP is connected, the skill instructs the agent to call the tools and deliver real MIDI and audio — not text-only sketches.

Versioning

nobu follows Semantic Versioning (MAJOR.MINOR.PATCH). See CHANGELOG.md (Keep a Changelog categories).

There is no [Unreleased] section — Cursor session hooks cut a new version whenever a conversation ends with meaningful changes.

Contributing

See CONTRIBUTING.md and CODE_OF_CONDUCT.md.

License

MIT — Copyright (c) 2026 nobu contributors.

nobu (Português)

Toolkit MCP game-agnostic para compor MIDI chiptune/retrô e renderizar áudio de jogo.

Cole isso no seu agente

Clone https://github.com/francescojr/nobu.git.
Leia nobu/AGENTS.md e rode: python scripts/bootstrap.py --no-prompt
Se for um projeto de jogo, rode também: python scripts/bootstrap.py --integrate <raiz_deste_projeto> --no-prompt
Recarregue o MCP, confirme o server "nobu" (16 tools: compose + Mega Drive + render).
Siga .claude/skills/game-music-producer/ — compose, render e/ou VGM quando eu pedir.

Início rápido (manual)

git clone https://github.com/francescojr/nobu.git
cd nobu
python scripts/bootstrap.py          # humano: menu interativo de optionals
python scripts/bootstrap.py --no-prompt --smoke   # agente: prova chip sem MCP
python examples/demo_biome_ost.py
python scripts/render_midi.py --mode chip   # funciona sem SF2

Modos: chip (puro) · hybrid (SF2 drums + chip) · sf2 (SoundFont completo).
Sem SF2/FluidSynth → fallback automático para chiptune (não quebra).
SF2: FluidSynth → WAV → OGG (ffmpeg recomendado no Windows).

Detalhes: AGENTS.md · SETUP.md.

Pastas

Tools MCP (inglês)

Compose: start_project → suggest_scale_for_mood → add_layer → list_layers → export_midi
Mega Drive: get_megadrive_capabilities → export_megadrive
Render: render_project / render_chip / render_hybrid / render_sf2 / render_all_modes

Licença

MIT.