This MCP server lets an AI tool compose and manage music in Bosca Ceoil Blue and control the app.
Create, open, save, import MIDI, read, and update songs.
List voices, get drumkits, and add, update, or remove instruments.
Add, edit, clone, and remove patterns with notes, keys, scales, instruments, and filter automation.
Edit the bar-based arrangement and loop range.
Play, pause, and stop playback through the user's speakers.
Export songs to WAV, MIDI, MML, or XM and check WAV export status.
Undo and redo edits.
Check app status, launch or quit the app, focus views/patterns/instruments, and screenshot the app window.
Masters an exported WAV for Amazon Music through the master_wav tool, targeting -14 LUFS with a -1 dBTP true-peak ceiling.
Masters an exported WAV for Apple Music via the master_wav tool, targeting -16 LUFS with a -1 dBTP true-peak ceiling.
Masters an exported WAV for release on Spotify through the master_wav tool, bringing the track to Spotify's -14 LUFS loudness target with a look-ahead limiter holding true peak under -1 dBTP.
Masters an exported WAV for TIDAL using the master_wav tool, applying a single overall gain to reach -14 LUFS while limiting true peak to -1 dBTP.
Masters an exported WAV for YouTube via the master_wav tool, targeting -14 LUFS with a -1 dBTP ceiling so the track isn't weak next to other music on the platform.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Bosca Ceoil MCP Write me a cheerful 8-bar chiptune and play it."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server that lets AI tools compose music in Bosca Ceoil Blue. Ask your AI tool for a song, and watch the notes appear in the app's window. Listen to it, undo anything with Ctrl+Z, and export it to WAV, MIDI, XM or MML.
This is an unofficial companion project, not affiliated with Bosca Ceoil Blue or its authors. You get the app separately, and it isn't modified.
The demo above is silent. Watch it with sound to hear the 8-bar loop the composer skill wrote for it.
You need Node.js 18 or newer, and Bosca Ceoil Blue unpacked somewhere on your computer.
git clone https://github.com/boraswim/bosca-ceoil-mcp.git
cd bosca-ceoil-mcp
npm installThen connect your AI tool. In the examples below, replace:
/path/to/bosca-ceoil-mcp with the folder you cloned.
/path/to/boscaceoil-blue with the app's executable or the folder it's in. Use forward slashes on Windows too.
Restart the AI tool afterwards, and ask it something like "Write me a cheerful 8-bar chiptune in Bosca Ceoil."
claude mcp add bosca-ceoil --scope user -- node /path/to/bosca-ceoil-mcp/dist/index.js --app-path /path/to/boscaceoil-bluecodex mcp add bosca-ceoil -- node /path/to/bosca-ceoil-mcp/dist/index.js --app-path /path/to/boscaceoil-blueOr add this to ~/.codex/config.toml:
[mcp_servers.bosca-ceoil]
command = "node"
args = ["/path/to/bosca-ceoil-mcp/dist/index.js", "--app-path", "/path/to/boscaceoil-blue"]Add this to ~/.gemini/config/mcp_config.json, or to .agents/mcp_config.json in a workspace. In the IDE, you can open it from the MCP Servers panel, with Manage MCP Servers and then View raw config.
{
"mcpServers": {
"bosca-ceoil": {
"command": "node",
"args": ["/path/to/bosca-ceoil-mcp/dist/index.js", "--app-path", "/path/to/boscaceoil-blue"]
}
}
}This is a standard MCP server over stdio, so any tool that supports those can use it, with the same command and arguments. The ChatGPT website and app only reach remote servers, so they can't use it.
Related MCP server: Filopastry
Argument | Environment variable | What it does |
|
| Where the app is. Without it, the server looks through Downloads, Desktop, Applications, Games, Program Files and itch.io's folder for it. |
|
| Runs the app with no window or sound. Useful for automation, but WAV exports take about twice as long, and unsaved work is lost 30 seconds after the AI tool disconnects. |
Area | Tools |
Songs |
|
Instruments |
|
Patterns |
|
Arrangement |
|
Playback |
|
Export |
|
History |
|
App |
|
Streaming platforms play every track at about the same loudness, so a quiet export sounds weak next to other music. master_wav masters an exported WAV for release. It brings the file to the platform's loudness target with one overall gain, and a look-ahead limiter keeps the true peak under the ceiling. Ask for a release when you request a song, for example "Write a 2-minute chiptune track I can release on Spotify".
| Target | Ceiling |
| -14 LUFS | -1 dBTP |
| -14 LUFS | -1 dBTP |
| -15 LUFS | -1 dBTP |
| -16 LUFS | -1 dBTP |
Use streaming when a distributor such as DistroKid or CD Baby sends one file to every store. You can also set your own target_lufs and true_peak_db. The limiter turns peaks down by 6 dB at most by default. If that isn't enough to reach the target, the tool stops short and says so, rather than squash the music. The original export is left as it is.
Your work is protected. Replacing a song with unsaved changes, overwriting a file, or quitting with unsaved changes all fail unless the AI tool explicitly says that's intended. An edit is one undo step in the app, whether you or the AI made it.
skills/bosca-ceoil-composer is an optional skill that helps Claude write game music and sound effects with this server. It has sound effect recipes, tempo and arrangement guidance for game moments, notes on how the app behaves, scripts that measure exports, cut seamless loops, finish sound effects and find clashing notes in a song, and demos you can listen to. The scripts need Python 3, and two of them need numpy.
To use it in Claude Code, copy that folder to ~/.claude/skills/, or to .claude/skills/ in your project. It's also listed on Agensi, where you can install it into Claude Code, Cursor, Codex and other agents. You still need this server set up.
The skill writes original material. Its guidance comes from aggregate measurements like tempo, length, density and pitch movement, and it contains no melodies or audio from these sources:
Source | Used for | License |
How retro sound effect presets are built | Unlicense | |
Interface Sounds by Kenney | UI sound measurements | CC0 |
100 CC0 SFX #2 by rubberduck | Sound effect measurements | CC0 |
Indiscriminate MIDI Music by blitzdoughnuts | Arrangement statistics | CC0 |
Original MIDI Album by roppychop | Checked for note grid fit | CC0 |
Procedural MIDI Music by Drummyfish | Checked for note grid fit | CC0 |
Incompetech by Kevin MacLeod | Tempo and instrument data by feel, from the catalog's track list |
AI tool <-- MCP over stdio --> Node server <-- JSON over local socket --> bridge.gd, inside the appThe server starts the normal Bosca Ceoil Blue executable with Godot's --script option, which loads bridge/boot.gd. That script starts the app as usual, and adds bridge/bridge.gd to it. The bridge works on the app's own objects and undo system, so edits show up live and follow the app's rules, and exports use the app's own code. No files in the app's folder change.
The bridge only listens on 127.0.0.1, and requires a random token stored in ~/.bosca-ceoil-mcp/session.json. That folder also holds app.log, the app's output from the last launch.
The app stays open when the AI tool closes, so your song isn't lost. A new session reconnects to it.
If you started the app yourself, the server can't reach it, and opens a second window. Save your work and close the first one, or open your song through the AI tool.
Tested on: Windows 11 with Bosca Ceoil Blue 3.1.2, using Claude Code and a scripted MCP client.
Not tested yet: Codex and Antigravity, which follow their documented setup, and macOS and Linux, which should work the same way. Please report what you find.
Other app versions: the bridge uses the app's internal code, so a future version could break it. You'd get an error saying so when starting up, and details in app.log.
Hearing: AI tools can't hear the song. A WAV export reports its duration, peak, RMS, loudness in LUFS and true peak, which catches silent, clipped or quiet output, but only you can tell if it sounds good.
WAV exports play the song through by default, so a long song takes as long as it plays. With fast: true, export_song renders it offline in a few seconds instead. In testing it matched the default export sample for sample, except with the compressor effect, whose live output also depends on what the app played before. It's opt-in while it gets more testing.
Filter automation past step 16 is lost on saving, a limit of the app's file format.
App's scale quirk: its minor scale is melodic, with a raised 6th and 7th. The server explains this to AI tools, since it's easy to trip over.
npm testThis builds the server and runs test/integration.mjs, which drives the real app without a window through a real MCP client. Set BOSCA_CEOIL_PATH to the app, or unpack it into a ref folder here. Your own settings aren't touched.
MIT. Bosca Ceoil Blue has its own MIT license.
Adds an instrument to the song. A song can have 16.
Inputs: voice (required), cutoff, volume, resonance.
Adds a pattern and returns its index. It won't play until the arrangement uses it. Notes are absolute pitches, so the key and scale don't move them; they must fit that key and scale.
Inputs: key, notes, scale, instrument.
Reports whether Bosca Ceoil Blue is running, plus its version, the current song's summary, and playback and export state. Doesn't start the app.
Inputs: no named parameters.
Copies a pattern to a new index, as a starting point for a variation.
Inputs: pattern (required).
Replaces the open song with a new one, optionally built in one go from settings, instruments, patterns and an arrangement. This is the quickest way to write a song. Without instruments and patterns, you get the app's default: one Grand Piano, and one empty pattern on bar 0.
Inputs: bpm, bars, swing, effect, +8 more.
Places patterns on the timeline. Each bar plays up to 8 patterns at once, on separate channels. Writes whole bars starting at at_bar, leaving other bars alone. Unless a loop is given, the loop then covers the whole song.
Inputs: bars (required), at_bar, loop_end, loop_start, +1 more.
Exports the song as audio or music data: wav (rendered audio), mid (MIDI), mml (SiON MML) or xm (FastTracker). A WAV renders at about playback speed or slower, so a long one returns state "rendering"; follow it up with export_status. A finished WAV reports its duration, peak and RMS, to help catch silent or clipped results.
Inputs: path (required), format (required), to_bar, from_bar, +2 more.
Reports how the current or most recent WAV export is going. The song can't be edited while it renders.
Inputs: no named parameters.
Shows something in the app's window: selects a pattern for the note grid, selects an instrument, or switches views.
Inputs: view, pattern, instrument.
Lists the items of a drumkit voice. In a drumkit pattern, each 'note' is one of these items instead of a pitch.
Inputs: voice (required).
Returns the whole song: settings, instruments, patterns with their notes, and the arrangement. Notes are in the same form the editing tools take.
Inputs: include_notes.
Replaces the open song with one imported from a MIDI file. Bosca is a step sequencer, so complex timing may not survive.
Inputs: path (required), pattern_size, discard_changes.
Starts Bosca Ceoil Blue. Other tools do this on demand, so it's only needed to choose the mode or to open the window before working.
Inputs: headless.
Lists the app's voices (over 300), to pick from when adding an instrument. Filter them, since the full list is long.
Inputs: query, category.
Opens a .ceol song file.
Inputs: path (required), discard_changes.
Pauses playback, keeping the position.
Inputs: no named parameters.
Plays the song through the user's speakers, looping until stopped. The AI tool can't hear it, so use this when the user wants to listen.
Inputs: from_bar.
Closes Bosca Ceoil Blue.
Inputs: discard_changes.
Redoes the last undone edit.
Inputs: no named parameters.
Removes an instrument. Later instruments move down one index, and patterns using it switch to instrument 0.
Inputs: instrument (required).
Removes a pattern and clears it from the arrangement. Later patterns move down one index.
Inputs: pattern (required).
Saves the song as a .ceol file. Songs aren't saved automatically.
Inputs: path, overwrite.
Captures the app's window as an image, to check what the user is seeing. Not available without a window.
Inputs: no named parameters.
Stops playback and goes back to the start of the loop.
Inputs: no named parameters.
Undoes the last edit, made by the user or by a tool. The app keeps 40 steps. Opening or creating a song clears them.
Inputs: no named parameters.
Changes an instrument's voice or settings. Every pattern using it changes too. Switching a pattern's instrument to a drumkit drops notes that have no matching item.
Inputs: instrument (required), voice, cutoff, volume, +1 more.
Edits a pattern's notes, key, scale, instrument or filter automation, as one undo step. Changing the key transposes its notes, like the app does. Changing the scale removes notes that don't fit it.
Inputs: pattern (required), key, notes, scale, +5 more.
Changes song settings. Takes effect immediately, even during playback.
Inputs: bpm, swing, effect, bar_size, +2 more.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 28 tools
Each tool targets a clearly distinct resource or operation, and the descriptions actively disambiguate the risky pairs (create_song vs open_song vs import_midi all replace the song; add_pattern vs clone_pattern both create patterns). Minor soft spots remain: export_song vs export_status and launch_app vs app_status are adjacent, and 'focus' is broad enough to be mistaken for a view/selection helper, but the descriptions resolve these.
The dominant pattern is verb_noun (create_song, update_pattern, remove_instrument, list_voices, export_status), applied consistently across the song/instrument/pattern families. Deviations are small and idiomatic: bare intransitive verbs (play, pause, stop, undo, redo) and noun-style status tools (app_status, export_status) break the strict pattern but remain predictable and readable.
28 tools is at the heavy end and pushes past the comfortable 3-15 band, though the domain (song, instruments, patterns, arrangement, playback, export, app lifecycle) is broad enough that most tools map to a real operation. A few could be consolidated without loss, e.g. play/pause/stop, export_song/export_status, and launch_app/quit_app/app_status, which is why this lands borderline rather than well-scoped.
Coverage is strong across the full lifecycle: app start/stop, song create/open/import/save/export, instrument and pattern CRUD with cloning, arrangement editing, playback, and undo/redo. Gaps are minor and workaroundable: there is no per-pattern or per-instrument getter (get_song dumps everything) and no way to delete a song file or close a song without replacing it.
Browser DAW for AI assistants: build multitrack songs with MIDI, effects, stems and generation.
Make and edit instrumental music from your agent: songs you can keep changing, MP3/WAV export
Compose, mix, master and export in Logic Pro, REAPER or Ableton Live by talking to an AI engineer.
Make AI Tracks, loops and sound effects, split stems, build drum kits and master songs.