{"id":50754545,"url":"https://github.com/ghchen99/mcp-musescore","last_synced_at":"2026-06-28T07:00:27.132Z","repository":{"id":302352923,"uuid":"1012003548","full_name":"ghchen99/mcp-musescore","owner":"ghchen99","description":"A Model Context Protocol (MCP) server that provides programmatic control over MuseScore!","archived":false,"fork":false,"pushed_at":"2026-04-23T19:19:18.000Z","size":19567,"stargazers_count":40,"open_issues_count":0,"forks_count":14,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-23T21:20:34.602Z","etag":null,"topics":["fastmcp","mcp-server","music"],"latest_commit_sha":null,"homepage":"","language":"QML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ghchen99.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-01T16:53:11.000Z","updated_at":"2026-04-23T19:19:22.000Z","dependencies_parsed_at":null,"dependency_job_id":"6cba068d-0089-46a3-8557-3c48b39e39af","html_url":"https://github.com/ghchen99/mcp-musescore","commit_stats":null,"previous_names":["ghchen99/mcp-musescore"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ghchen99/mcp-musescore","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ghchen99%2Fmcp-musescore","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ghchen99%2Fmcp-musescore/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ghchen99%2Fmcp-musescore/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ghchen99%2Fmcp-musescore/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ghchen99","download_url":"https://codeload.github.com/ghchen99/mcp-musescore/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ghchen99%2Fmcp-musescore/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34880189,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-28T02:00:05.809Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fastmcp","mcp-server","music"],"created_at":"2026-06-11T04:00:24.044Z","updated_at":"2026-06-28T07:00:27.125Z","avatar_url":"https://github.com/ghchen99.png","language":"QML","funding_links":[],"categories":["MCP Servers for Creative Work"],"sub_categories":["Music \u0026 Live Coding"],"readme":"# MuseScore MCP Server\n\nA Model Context Protocol (MCP) server that provides programmatic control over MuseScore, via a WebSocket-based plugin system. This allows AI assistants like Claude to compose music, add lyrics, navigate scores, and control MuseScore directly.\n\n![Demo GIF](./assets/mcp-muse.gif)\n\n## Prerequisites\n\n- MuseScore 3.x or 4.x\n- Python 3.8+\n- Claude Desktop or compatible MCP client\n\n## Setup\n\n### 1. Install the MuseScore Plugin\n\nFirst, save the QML plugin code to your MuseScore plugins directory:\n\n**macOS**: `~/Documents/MuseScore4/Plugins/musescore-mcp-websocket.qml`\n**Windows**: `%USERPROFILE%\\Documents\\MuseScore4\\Plugins\\musescore-mcp-websocket.qml`\n**Linux**: `~/Documents/MuseScore4/Plugins/musescore-mcp-websocket.qml`\n\n### 2. Enable the Plugin in MuseScore\n\n1. Open MuseScore\n2. Go to **Plugins → Plugin Manager**\n3. Find \"MuseScore API Server\" and check the box to enable it\n4. Click **OK**\n\n### 3. Setup Python Environment\n\n```bash\ngit clone \u003cyour-repo\u003e\ncd mcp-agents-demo\npython -m venv .venv\nsource .venv/bin/activate  # On Windows: .venv\\Scripts\\activate\npip install fastmcp websockets\n```\n\n### 4. Configure Claude Desktop\n\nAdd to your Claude Desktop configuration file:\n\n**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n**Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"musescore\": {\n      \"command\": \"/path/to/your/project/.venv/bin/python\",\n      \"args\": [\n        \"/path/to/your/project/server.py\"\n      ]\n    }\n  }\n}\n```\n\n**Note**: Update the paths to match your actual project location.\n\n## Running the System\n\n### Order of Operations\n\n1. **Start MuseScore first** with a score open\n2. **Run the MuseScore plugin**: Go to **Plugins → MuseScore API Server**\n   - You should see console output: `\"Starting MuseScore API Server on port 8765\"`\n3. **Then start the Python MCP server** or restart Claude Desktop\n\n[insert screenshot of different functionality, harmonisation, melodywriting, as zoomed in GIFs]\n\n### Development and Testing\n\nFor development, use the MCP development tools:\n\n```bash\n# Install MCP dev tools\npip install mcp\n\n# Test your server\nmcp dev server.py\n\n# Check connection status\nmcp dev server.py --inspect\n```\n\n### Viewing Console Output\n\nTo see MuseScore plugin console output, run MuseScore from terminal:\n\n**macOS**:\n```bash\n/Applications/MuseScore\\ 4.app/Contents/MacOS/mscore\n```\n\n**Windows**:\n```cmd\ncd \"C:\\Program Files\\MuseScore 4\\bin\"\nMuseScore.exe\n```\n\n**Linux**:\n```bash\nmusescore4\n```\n\n## Features\n\nThis MCP server provides comprehensive MuseScore control. \n\n**🌟 NEW in this fork:** Built-in automatic, flawless multi-voice Polyphony \u0026 Temporal layout mapping to LilyPond!\n\n### **Navigation \u0026 Cursor Control**\n- `get_cursor_info()` - Get current cursor position and selection info\n- `go_to_measure(measure)` - Navigate to specific measure\n- `go_to_beginning_of_score()` / `go_to_final_measure()` - Navigate to start/end\n- `next_element()` / `prev_element()` - Move cursor element by element\n- `next_staff()` / `prev_staff()` - Move between staves\n- `select_current_measure()` - Select entire current measure\n- `select_custom_range(start_tick, end_tick, start_staff, end_staff)` - Slicing tool to extract cross-measure, multi-staff phrasing\n\n### **Polyphony \u0026 LilyPond Integration**\n- **Temporal Rhythm Padding**: Voices with gaps or rests automatically receive LilyPond spacer sequences (`s4.`) to hold their mathematical place accurately.\n- **Concurrent Voice Rendering**: Full 4-voice (`\\voiceOne`, `\\voiceTwo`, etc.) arrays correctly structured and sharded per staff for advanced Agent processing.\n\n### **Note \u0026 Rest Creation**\n- `add_note(pitch, duration, advance_cursor_after_action)` - Add notes with MIDI pitch\n- `add_rest(duration, advance_cursor_after_action)` - Add rests\n- `add_tuplet(duration, ratio, advance_cursor_after_action)` - Add tuplets (triplets, etc.)\n\n### **Measure Management**\n- `insert_measure()` - Insert measure at current position\n- `append_measure(count)` - Add measures to end of score\n- `delete_selection(measure)` - Delete current selection or specific measure\n\n### **Lyrics \u0026 Text**\n- `add_lyrics_to_current_note(text)` - Add lyrics to current note\n- `add_lyrics(lyrics_list)` - Batch add lyrics to multiple notes\n- `set_title(title)` - Set score title\n\n### **Score Information**\n- `get_score()` - Get complete score analysis and structure\n- `ping_musescore()` - Test connection to MuseScore\n- `connect_to_musescore()` - Establish WebSocket connection\n\n### **Utilities**\n- `undo()` - Undo last action\n- `set_time_signature(numerator, denominator)` - Change time signature\n- `processSequence(sequence)` - Execute multiple commands in batch\n\n## Sample Music\n\nCheck out the `/examples` folder for sample MuseScore files demonstrating various musical styles:\n\n- **Asian Instrumental** - Traditional Asian-inspired instrumental piece\n- **String Quartet** - Classical string quartet arrangement\n\nEach example includes:\n- `.mscz` - MuseScore file (editable)\n- `.pdf` - Sheet music\n- `.mp3` - Audio preview\n\n## Usage Examples\n\n### Creating a Simple Melody\n\n```python\n# Set up the score\nawait set_title(\"My First Song\")\nawait go_to_beginning_of_score()\n\n# Add notes (MIDI pitch: 60=C, 62=D, 64=E, etc.)\nawait add_note(60, {\"numerator\": 1, \"denominator\": 4}, True)  # Quarter note C\nawait add_note(64, {\"numerator\": 1, \"denominator\": 4}, True)  # Quarter note E\nawait add_note(67, {\"numerator\": 1, \"denominator\": 4}, True)  # Quarter note G\nawait add_note(72, {\"numerator\": 1, \"denominator\": 2}, True)  # Half note C\n\n# Add lyrics\nawait go_to_beginning_of_score()\nawait add_lyrics_to_current_note(\"Do\")\nawait next_element()\nawait add_lyrics_to_current_note(\"Mi\")\nawait next_element()\nawait add_lyrics_to_current_note(\"Sol\")\nawait next_element()\nawait add_lyrics_to_current_note(\"Do\")\n```\n### Batch Operations\n\n```python\n# Add multiple lyrics at once\nawait add_lyrics([\"Twin-\", \"kle\", \"twin-\", \"kle\", \"lit-\", \"tle\", \"star\"])\n\n# Use sequence processing for complex operations\nsequence = [\n    {\"action\": \"goToBeginningOfScore\", \"params\": {}},\n    {\"action\": \"addNote\", \"params\": {\"pitch\": 60, \"duration\": {\"numerator\": 1, \"denominator\": 4}, \"advanceCursorAfterAction\": True}},\n    {\"action\": \"addNote\", \"params\": {\"pitch\": 64, \"duration\": {\"numerator\": 1, \"denominator\": 4}, \"advanceCursorAfterAction\": True}},\n    {\"action\": \"addRest\", \"params\": {\"duration\": {\"numerator\": 1, \"denominator\": 4}, \"advanceCursorAfterAction\": True}}\n]\nawait processSequence(sequence)\n```\n\n## Star History\n\n[![Star History Chart](https://api.star-history.com/image?repos=ghchen99/mcp-musescore\u0026type=date\u0026legend=top-left)](https://www.star-history.com/?repos=ghchen99%2Fmcp-musescore\u0026type=date\u0026legend=top-left)\n\n## Troubleshooting\n\n### Connection Issues\n- **\"Not connected to MuseScore\"**: \n  - Ensure MuseScore is running with a score open\n  - Run the MuseScore plugin (Plugins → MuseScore API Server)\n  - Check that port 8765 isn't blocked by firewall\n\n### Plugin Issues\n- **Plugin not appearing**: Check the `.qml` file is in the correct plugins directory\n- **Plugin won't enable**: Restart MuseScore after placing the plugin file\n- **No console output**: Run MuseScore from terminal to see debug messages\n\n### Python Server Issues\n- **\"No server object found\"**: The server object must be named `mcp`, `server`, or `app` at module level\n- **WebSocket errors**: Make sure MuseScore plugin is running before starting Python server\n- **Connection timeout**: The MuseScore plugin must be actively running, not just enabled\n\n### API Limitations\n- **Lyrics**: Only first verse supported in MuseScore 3.x plugin API\n- **Title setting**: Uses multiple fallback methods due to frame access limitations\n- **Selection persistence**: Some operations may affect current selection\n\n## File Structure\n\n```\nmcp-agents-demo/\n├── .venv/\n├── server.py                           # Python MCP server entry point\n├── musescore-mcp-websocket.qml         # MuseScore plugin\n├── requirements.txt\n├── README.md\n└── src/                                # Source code modules\n    ├── __init__.py\n    ├── client/                         # WebSocket client functionality\n    │   ├── __init__.py\n    │   └── websocket_client.py\n    ├── tools/                          # MCP tool implementations\n    │   ├── __init__.py\n    │   ├── connection.py               # Connection management tools\n    │   ├── navigation.py               # Score navigation tools\n    │   ├── notes_measures.py           # Note and measure manipulation\n    │   ├── sequences.py                # Batch operation tools\n    │   ├── staff_instruments.py        # Staff and instrument tools\n    │   └── time_tempo.py               # Timing and tempo tools\n    └── types/                          # Type definitions\n        ├── __init__.py\n        └── action_types.py             # WebSocket action type definitions\n```\n\n## MIDI Pitch Reference\n\nCommon MIDI pitch values for reference:\n- **Middle C**: 60\n- **C Major Scale**: 60, 62, 64, 65, 67, 69, 71, 72\n- **Chromatic**: C=60, C#=61, D=62, D#=63, E=64, F=65, F#=66, G=67, G#=68, A=69, A#=70, B=71\n\n## Duration Reference\n\nDuration format: `{\"numerator\": int, \"denominator\": int}`\n- **Whole note**: `{\"numerator\": 1, \"denominator\": 1}`\n- **Half note**: `{\"numerator\": 1, \"denominator\": 2}`\n- **Quarter note**: `{\"numerator\": 1, \"denominator\": 4}`\n- **Eighth note**: `{\"numerator\": 1, \"denominator\": 8}`\n- **Dotted quarter**: `{\"numerator\": 3, \"denominator\": 8}`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fghchen99%2Fmcp-musescore","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fghchen99%2Fmcp-musescore","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fghchen99%2Fmcp-musescore/lists"}