nuclear README

The project's README from github.com/nukeop/nuclear. As one markdown file: README.md.

Nuclear Music Player

Nuclear

Nuclear is a free, open-source music player without ads or tracking. Search for any song or artist, build playlists, and start listening.
Runs on Windows, macOS, and Linux.

Screenshots

Nuclear Music Player - Dashboard

Nuclear comes with multiple built-in themes:

Green theme Aqua theme Mint theme

Orange theme Red theme Violet theme

Search artists Search albums
Artist search Album search
Playlists Plugin store
Playlists Plugin store
Installed plugins Preferences
Installed plugins Preferences
What's new Log viewer
What's new Log viewer

Download

Grab the latest release for your platform from the Releases page.

Platform Formats
Windows .exe installer, .msi
macOS .dmg (Apple Silicon and Intel)
Linux .AppImage, .deb, .rpm, .flatpak

Features

Plugins

Nuclear has a powerful plugin system now! Every functionality has been redesigned to be driven by plugins.

Plugins can provide streaming sources, metadata, playlists, dashboard content, and more. Browse and install plugins from the built-in plugin store, or write your own using the @nuclearplayer/plugin-sdk.

MCP

You can enable the MCP server in Settings → Integrations.

Then to add it to Claude Code:

claude mcp add nuclear --transport http http://127.0.0.1:8800/mcp

Codex CLI:

codex mcp add nuclear --url http://127.0.0.1:8800/mcp

OpenCode:

{
  "mcp": {
    "nuclear": {
      "type": "remote",
      "url": "http://127.0.0.1:8800/mcp"
    }
  }
}

Claude Desktop / Cursor / Windsurf:

{
  "mcpServers": {
    "nuclear": {
      "url": "http://127.0.0.1:8800/mcp"
    }
  }
}

The MCP is designed to be discoverable, but there's a skill you can load to get your AI up to speed: Nuclear MCP Skill

Development

Nuclear is a pnpm monorepo managed with Turborepo. The main app is built with Tauri (Rust + React).

Prerequisites

Getting started

git clone https://github.com/nukeop/nuclear.git
cd nuclear
pnpm install
pnpm dev

Useful commands

pnpm dev            # Run the player in dev mode
pnpm dev:remote     # Same, but binds Vite to 0.0.0.0 so you can open the remote control UI from other devices on your LAN
pnpm build          # Build all packages
pnpm test           # Run all tests
pnpm lint           # Lint all packages
pnpm type-check     # TypeScript checks
pnpm storybook      # Run Storybook

Community

License

AGPL-3.0. See LICENSE.

nuclear (nukeop/nuclear)

Searching Database…

18.7K ·GitHub
What is this?Nuclear is a free, open-source desktop music player that finds free music for you: search for any song or artist, stream it, and build playlists.
Is this a desktop app or does it run in the browser?It's a native desktop app you install on your machine — the current version is built with Tauri (a Rust backend with a React interface), not a web app.
Do I need an account or any extra setup to start listening?No — install it and search for music right away; there are no accounts or subscriptions. Only building from source needs extra tools: Node.js 22+, pnpm 9+, and stable Rust.
Where does the music come from — is there a catalog like Spotify's?It's built around free music: Nuclear searches for and streams music from any source rather than selling access to a licensed catalog, so what you can hear depends on the sources available to it.
Which platforms does it run on?Windows, macOS, and Linux — including both Apple Silicon and Intel Macs.
Does it track me or show ads?No — the README says it outright: a music player without ads or tracking, and it's open source, so the code is inspectable.
What can plugins do?A lot — every core function is plugin-driven. Plugins add streaming sources, metadata, playlists and dashboard content; install them from the built-in plugin store or write your own with the @nuclearplayer/plugin-sdk.
Can I control the player with an AI agent?Yes — enable the MCP server in Settings → Integrations, then connect Claude Code, Codex CLI, OpenCode, Claude Desktop, Cursor or Windsurf. The MCP is designed to be discoverable, and a Nuclear MCP Skill can bring your agent up to speed.
What's included besides search and playback?Queue management with shuffle, repeat and drag-and-drop reordering; favorites for albums, artists and tracks; playlist import and export, including from other services; auto-updates; keyboard shortcuts; multiple interface languages; and a log viewer.
Can I customize how it looks?Yes — Nuclear ships with several built-in themes and also supports custom CSS themes, so you can restyle the player yourself.
Creator
nukeop
Size
219.9 MB
Stars
18.7K
Age
10y
Commits · 90 Days