# MoeKoe Music: a third-party KuGou client for Windows, macOS, Linux and the browser

> MoeKoe Music wraps a KuGou account, a Vue 3 front end and a bundled Node API into an Electron desktop app, with a Docker path for the web build. Here is how the pieces fit, where the documentation stops, and who should stay with the official client.

**MoeKoeMusic/MoeKoeMusic** — 一款开源简洁高颜值的酷狗第三方客户端 An open-source, concise, and aesthetically pleasing third-party client for KuGou that supports  Windows / macOS / Linux / Web :electron:

- Repository: https://github.com/MoeKoeMusic/MoeKoeMusic
- Website: https://Music.MoeKoe.cn
- Stars: 6,380 · Forks: 401
- Language: Vue
- License: GPL-2.0
- Published: 2026-09-22 · Updated: 2026-09-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/moekoemusic-moekoemusic

## What MoeKoe Music is, and the KuGou account it assumes you already have

MoeKoe Music is an open-source third-party client for KuGou, the Chinese music service. The README describes it as "一款开源简洁高颜值的酷狗第三方客户端" and the repository topics list electron, kugou, vue3, windows, macos and linux. The author's preface explains the motive: a KuGou library built up over roughly a decade, failed attempts to migrate those playlists into NetEase Cloud Music or QQ Music, and a Mac KuGou client that "时常可能会出现不能播放的情况". This is not a streaming service and it does not host audio. It is a different window onto an account you already have.

The audience is narrow and specific. You need a KuGou account, because the feature list begins with account login by QR code, phone number or username. You need to accept that the client talks to KuGou's own servers: one listed feature is "官方服务器直连", a direct connection to the official servers. And you need to be comfortable with a Chinese-language product, even though the repository ships translated READMEs in Traditional Chinese, Japanese, English, Korean and Russian. If you do not use KuGou, nothing here applies to you.

## How the Electron app, the bundled API and the Vue front end fit together

The repository layout separates three concerns. src/ holds the Vue front end, electron/ holds the desktop shell, and api/ holds a Node service. The package.json main field points at electron/main.js, and the dev script chains all three: it runs the API, then Vite, then Electron. The API is not a thin proxy you can ignore. The api script in package.json starts it as node api/app.js --platform=lite --port=6521, so the default port is 6521 and the platform flag is lite.

The Dockerfile shows the same split in production form. Stage one is a node:20-alpine builder that deletes electron and electron-builder from package.json before running npm install, then builds the front end with npm run build:docker, which sets VITE_APP_API_URL to /api. Stage two installs Nginx, copies the api directory, installs its production dependencies, copies the built dist/ folder, and starts both processes from one CMD: the Node API in the background and Nginx in the foreground. Nginx serves the static front end on 8080 and proxies the API, which listens on 6521. That is the whole architecture: a static Vue bundle, a Node process that speaks to KuGou, and a desktop wrapper that bundles the same two pieces.

The feature list also mentions a plugin system ("超级插件系统") and the repository has a top-level plugins/ directory, but the README does not document a plugin API, a manifest format or a loading mechanism. The related searches include "MusicFree plugin", which suggests people arrive expecting compatibility with MusicFree's plugin model; nothing in the repository confirms that MoeKoe Music uses it.

## Installing the desktop client from GitHub Releases

The README's install section is short. For the client, it says to visit the Releases page and download the installer. There is no checksum, no signature verification step and no per-platform table in the README itself. The release list at the time of writing ends at v1.7.0, published on 2026-08-26, with v1.6.9 on 2026-07-21 and v1.6.8 on 2026-07-08 before it.

If your platform is missing from the release assets, the README tells you to build it yourself. Node.js 18.0.0 or newer is required there, while package.json declares engines.node as >=20. Treat the stricter number as the real floor. The build sequence is:

```bash
git clone https://github.com/iAJue/MoeKoeMusic.git
cd MoeKoeMusic
npm install
npm run build:api:linux
npm run electron:build:linux
```

The first two commands fetch the source and install dependencies. The third compiles the API server for your platform; the README lists build:api:win, build:api:linux and build:api:macos. The fourth packages the Electron app. The README states that output lands in /dist_electron, and that the default Linux target is AppImage, the default Windows target is an NSIS installer, and the macOS build is dual-architecture by default. Electron-builder's own documentation is linked for the flags.

## Running the web build with Docker on ports 8080 and 6521

The web path is the better-documented one. The README labels the quick start as recommended and gives a clone with submodules:

```bash
git clone https://github.com/iAJue/MoeKoeMusic.git
cd MoeKoeMusic
git submodule update --init --recursive
docker compose up -d &
```

The submodule step matters because the repository has a .gitmodules file and the development instructions use git clone --recurse-submodules. Skipping it leaves the API or a theme asset missing. The README warns that after deploying you must open the corresponding server port or put a reverse proxy in front of it for domain access.

The docker-compose.yml in the repository builds locally rather than pulling an image. It sets PORT=6521 and platform=lite, maps 8080:8080 for the front end and 6521:6521 for the API, and uses restart: unless-stopped. There is a docker run alternative in the README pointing at iajue/moekoe-music:latest with the same two ports and the same two environment variables. Be careful with that one: the README marks the related docker-compose method as struck through with the note that the image was not uploaded officially at the time of writing, so the pull path and the local build path may not be equally current. The third option, a Baota panel compose file, uses a mirror at registry.cn-wulanchabu.aliyuncs.com and the README says that remote image may lag behind the official one.

The one-click deploy button targets EdgeOne Pages and requires you to set VITE_APP_API_URL to your own API address in the environment variables. That is a front-end-only deployment: you still have to host the API somewhere.

## The VIP daily check-in, the missing rollback story, and where this client is the wrong tool

The most consequential line in the feature list is "每日自动领取VIP，登录就是VIP", a daily automatic VIP claim that the README summarizes as logging in means VIP. This is not a licence or a purchased subscription. It is an automated action against a third-party service, and it depends entirely on KuGou continuing to offer that daily claim and on the client's implementation of it continuing to work. Nothing in the repository documents what happens when the claim fails, or whether the client retries. If your listening depends on that VIP state, you are depending on someone else's server-side promotion.

The API service is the second soft spot. It is a Node process that speaks to KuGou on your behalf, and the README does not document its endpoints, its authentication flow, or how it handles a KuGou API change. There is no versioned interface described anywhere in the repository. When KuGou changes something, the fix lands as a new release, and you upgrade.

Rollback is undocumented. The README does not describe how to downgrade an installed client, whether settings survive a reinstall, or where the local database lives. For a desktop music player that is usually tolerable. For the Docker deployment it is less so, because the compose file builds from the working tree: if you pull a new commit and run docker compose up -d again, you get whatever is on the branch. Pin a tag or a commit if you care about reproducibility.

Finally, this is the wrong tool if you want a client that does not require an account, or one whose behaviour you can reason about from documentation alone. The README is a feature list and a build guide. It is not a specification.

## How MoeKoe Music differs from YesPlayMusic and NeteaseCloudMusicApi

The related searches point at YesPlayMusic, NeteaseCloudMusicApi, TTKMusicPlayer, AlgerMusic and MusicFree. The useful comparison is YesPlayMusic, because the two projects occupy the same slot for different services. YesPlayMusic is a third-party client for NetEase Cloud Music; MoeKoe Music is a third-party client for KuGou. The difference is not the interface, it is the catalogue and the account. If your library, your playlists and your VIP status live on KuGou, YesPlayMusic cannot see any of it, and the author's preface describes exactly that failure when trying to move a KuGou playlist elsewhere.

NeteaseCloudMusicApi is a different kind of project: an API server for NetEase Cloud Music, not a player. MoeKoe Music does ship an API service, but the README presents it as an internal component of the client and the web deployment, not as a documented interface for third parties. If what you want is an API to build your own front end against, NeteaseCloudMusicApi is the closer fit in shape, though for a different music service.

MusicFree and its plugin model come up in search, and MoeKoe Music does advertise a plugin system. The README does not describe the plugin format, so anyone arriving with a MusicFree plugin expecting it to load should verify that against the repository's plugins/ directory before assuming compatibility. TTKMusicPlayer and AlgerMusic appear in the same search results; the repository says nothing about how they work, so no comparison is possible.

## Maintenance, licence and what an upgrade actually costs you

The repository is not archived, and the last push was on 2026-09-03. The release cadence visible in the release list is roughly one release a month: v1.6.8 on 2026-07-08, v1.6.9 on 2026-07-21, v1.7.0 on 2026-08-26. The package.json version field reads 1.7.0, matching the latest release tag, which suggests the version is bumped in the manifest at release time.

Upgrade cost depends on how you installed it. Desktop users replace the installer; there is no documented migration step between versions, and no documented settings export. Docker users rebuild from the working tree, which means an upgrade is a git pull plus docker compose up -d, and a rollback is a checkout of an earlier commit plus the same command. The README does not describe either procedure, so treat the compose file as something you should pin yourself.

The licence is GPL-2.0, stated in the repository's LICENSE file and shown in the README badge. For anyone running the client on their own machine that changes nothing. For anyone considering shipping a modified build, GPL-2.0 carries source-disclosure obligations, and this project bundles a Node API and an Electron shell rather than being a library you link against. The repository also carries a CODE_OF_CONDUCT.md and a CONTRIBUTING.md, so contributions are expected to follow those. This is a description of the licence as stated, not legal advice; read the LICENSE file and talk to someone qualified if you plan to redistribute.

## Conclusion

Adopt MoeKoe Music if you already live inside a KuGou account and want a quieter desktop player with lyrics, daily recommendations and no social feed. Skip it if you need a documented API contract, a rollback story, or a client that does not depend on KuGou's servers staying reachable and its VIP rules staying as they are. Before installing, read the release notes for v1.7.0 and check the docs/README_en.md file, which is the English translation of the README; it is the only English entry point in the repository, and the changelog lives at music.moekoe.cn/changelog.html rather than in the repo.

## FAQ

### Does MoeKoe Music work without a KuGou account?

No. Account login by QR code, phone number or username is the first item in the feature list, and the client connects directly to KuGou's official servers. The daily VIP claim is tied to that same login.

### How do I run MoeKoe Music in a browser instead of installing the desktop app?

Use the Docker path from the README: clone the repository, run git submodule update --init --recursive, then docker compose up -d. The compose file exposes the front end on 8080 and the API on 6521, and the README notes you must open those ports or put a reverse proxy in front.

### Which Node.js version does MoeKoe Music need to build from source?

The README says Node.js 18.0.0 or newer, but package.json declares engines.node as >=20. Use 20 or later to match the manifest, which is also the version the Dockerfile builds on.

## Sources

- [License: GPL-2.0](https://github.com/MoeKoeMusic/MoeKoeMusic/blob/main/LICENSE)
- [MoeKoeMusic/MoeKoeMusic on GitHub](https://github.com/MoeKoeMusic/MoeKoeMusic)
- [Project website](https://Music.MoeKoe.cn)
- [README](https://github.com/MoeKoeMusic/MoeKoeMusic/blob/main/README.md)
- [Releases](https://github.com/MoeKoeMusic/MoeKoeMusic/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/moekoemusic-moekoemusic