English · 简体中文
NetEase Cloud Music for your terminal, applications, AI tools, and web pages. Built in Go, with a separately published web player.
| I want to… | Use | Start here |
|---|---|---|
| Search and manage music from a terminal | kite CLI; no server required |
CLI |
| Call music APIs from an application | kite-server with gRPC and REST |
Server |
| Give an AI client read-only music tools | kite mcp, running locally over stdio |
AI clients |
| Embed a player on a website | @violetjs/kite-player, with Web Components and React bindings |
Web player |
The CLI and server share the same NetEase request engine. The web player is an independent npm package; it connects to the server's public, read-only API or your own backend.
Download a binary from GitHub Releases, or install with Go (required version: go.mod):
go install github.com/VOD-Studio/kite/cmd/kite@latest
kite --help
kite search "周杰伦"Run kite login to sign in with a QR code when you need account-specific features. Playback and download availability depend on your NetEase account and the track's rights.
The CLI connects directly to NetEase; you do not need to run kite-server. See the getting-started guide. For commands and flags, use kite <command> --help or the generated reference.
Run locally from source:
git clone https://github.com/VOD-Studio/kite.git
cd kite
go run ./cmd/serverIn another terminal:
curl --fail http://127.0.0.1:3721/healthz
# {"status":"SERVING"}| Interface | Default address |
|---|---|
| REST | 127.0.0.1:3721 |
| gRPC | 127.0.0.1:3722 |
Local-only by default. Binding to a non-loopback address requires an access token; otherwise the server refuses to start. Server access tokens and NetEase login credentials serve different purposes.
Use the integration guide for authentication, account handling, and client examples. For containers, use the published image ghcr.io/vod-studio/kite-server with the configuration in server security; production rollout is covered in deployment.
After installing the CLI, register it with Claude Code:
claude mcp add kite -- kite mcpMCP exposes read-only tools for search, lyrics, playlists, and more. It uses your local CLI login state and cannot modify your music account. Claude Desktop and Cursor configuration: MCP guide.
npm install @violetjs/kite-playerA floating player, track and playlist cards, word-by-word lyrics, and mobile layouts. Use custom elements in any framework, React components and hooks, or the playback core with your own UI.
The browser-facing /player/v1 API is separate from the authenticated gRPC/REST service. It exposes only allowlisted content, with signed playback links and rate limiting. Never put server access tokens or NetEase cookies in page markup.
Detailed guides and CLI help are currently in Simplified Chinese. Both this overview and the player README are available in English and Chinese.
| Topic | Reference |
|---|---|
| CLI usage | Getting started · Command reference |
| Application integration | Client guide · gRPC/REST errors |
| Server operations | Security and configuration · Production deployment |
| AI tools | MCP setup · Project index for agents |
| Web player | Package documentation · Public API |
| Contracts and design | Protobuf definitions · Buf Schema Registry · ADRs |
| Changes and planned work | Go changelog · Player changelog · Issues |
Use the Go version in go.mod and the Node.js major version in Makefile. From a checkout:
go build ./cmd/server/ ./cmd/kite/
go test ./...
make player-demo # Build and open a local, offline player demo serverThe demo uses fictional songs and simulated playback; it needs neither NetEase credentials nor a running kite server. Open the URL printed by the command.
See CONTRIBUTING for the Docker toolchain, code generation, checks, and release process; see player development for package-specific workflows. Architecture boundaries are documented in AGENTS.md and enforced by tests.
MIT. For vulnerability reports, follow SECURITY.md rather than opening a public issue.