Tuisic MCP server
Commit Sep 16, 2026Lets an AI client search, play, and manage online music streaming from a terminal TUI via MCP.
Also known as Dark-Kernel/tuisic
- Stars
- 76
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Sep 16, 2026
- License
- GPL-3.0
What is Tuisic MCP?
Tuisic lets an AI client search, play, and manage online music streaming from a terminal TUI via MCP.
Summary generated from the project's README
About Tuisic MCP server
Managing and playing music through a terminal interface is possible via tuisic. This tool allows users to search for songs and control streaming playback directly from a command line interface using Vim motions. It functions as a local MCP server that connects to AI clients through the command tuisic --mcp-server, enabling an AI to interact with your music library and online sources.
Users can access music from various platforms including SoundCloud, YouTube, JioSaavn, and LastFM. The server also handles local music files by scanning a configured directory, such as the default ~/Music path, and playing them through mpv. Beyond simple playback, it supports features like playlist management, song downloads, and a favorites list. It integrates with system tools like playerctl for MPRIS support and can display lyrics or use a Cava visualizer during playback.
What you can do with it
- 1Search and play online musicAsk your AI client to find and start playing a specific song from SoundCloud or YouTube.
- 2Manage local music librariesInstruct an AI to scan your local music folder and play files from your personal collection.
- 3Download songs for offline useHave your AI assistant download a track you are currently listening to.
- 4Organize music favoritesTell the AI to add the current track to your list of favorite songs.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
BREW_PREFIXCMAKE_PREFIX_PATHHOMEBREW_PREFIXPKG_CONFIG_PATH
| Name | Description | |
|---|---|---|
| BREW_PREFIX | — | |
| CMAKE_PREFIX_PATH | — | |
| HOMEBREW_PREFIX | — | |
| PKG_CONFIG_PATH | — |
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachabledark-kernel/tuisic is public and reachablegithub.com/dark-kernel/tuisic ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)GPL-3.0spdx.org/licenses/GPL-3.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-09-16github.com/dark-kernel/tuisic ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubTUISIC
TUI Online Music Streaming application with MCP support
https://github.com/user-attachments/assets/ef349a06-0d7e-488b-aa3d-de928d9b0eef
First app of its kind, It let's you search and play online songs from cli hassle free. Now it supports AI integration through MCP (BETA). Checkout Demo's below
Features
- Vim motions
- No browser, No Ads
- Easy downloads
- Multiple song sources
- Playlist support
- Easy Sharing
- Favourites List
- Configuration file
- Daemon mode (BETA, press 'w' to toggle)
- MPRIS DBUS support ( via
playerctl) - Cava Visualizer (BETA)
- Support for AI Integration via MCP (BETA)
- Support for Discord Rich Presence
- Lyrics support (BETA)
- Local music library playback
When Local Music is selected from the playlist menu, Tuisic scans the path
configured under local_music.path recursively. The default is ~/Music,
which includes the requested ~/Music/mp4s/mp3s layout. Local files are played
directly through mpv, so online search and local playback can be switched
between at any time. For example:
"local_music": {
"path": "/home/user/Music"
}
Shortcuts
| Key | Action |
|---|---|
q |
quit |
w |
toggle daemon mode |
> |
next song |
< |
previous song |
<space> |
play/pause |
Alt+l |
copy url |
d |
download song |
a |
add to favourites |
. |
seek forward |
, |
seek backward |
m |
mute |
L |
Toggle lyrics |
Sources
It fetches songs from some platforms:
- JioSaavn
- SoundCloud
- LastFM
- ForestFM
- YouTube
- YouTube Music (on the way)
Installation:
yay -S tuisic-git
Building from source
Build Options
| CMake Flag | Description | Default |
|---|---|---|
-DWITH_MPRIS |
Enable MPRIS (sdbus-c++) support | ON |
-DWITH_CAVA |
Enable Cavacore-based visualizer | OFF |
-DWITH_DISCORD |
Enable Discord Rich Presence | OFF |
Before Installation
Update the desktop/tuisic.desktop file.
Exec=alacritty -e tuisic # Change terminal accordingly
Debian
- Install dependencies
sudo apt-get update
sudo apt-get install -y build-essential cmake pkg-config libfftw3-dev libmpv-dev libcurl4-openssl-dev libfmt-dev libsystemd-dev rapidjson-dev libpulse-dev
git clone --depth 1 https://github.com/Kistler-Group/sdbus-cpp.git
cd sdbus-cpp
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
cmake --build .
sudo cmake --build . --target install
- Build
cmake .. -DCMAKE_BUILD_TYPE=Release
cmake --build . --config Release -j$(nproc 2>/dev/null || sysctl -n hw.ncpu 2>/dev/null || echo 2)
Arch Linux
- Install dependencies
sudo pacman -S curl mpv fmt yt-dlp fftw sdbus-cpp rapidjson
- Build
cmake .. -DCMAKE_BUILD_TYPE=Release
cmake --build . --config Release -j$(nproc 2>/dev/null || sysctl -n hw.ncpu 2>/dev/null || echo 2)
MacOS
- Install dependencies
brew install cmake pkg-config fftw mpv curl fmt rapidjson
- Set environment variables for Homebrew paths
# Detect Homebrew prefix (Apple Silicon uses /opt/homebrew, Intel uses /usr/local)
BREW_PREFIX=$(brew --prefix)
export HOMEBREW_PREFIX=${BREW_PREFIX}
export PKG_CONFIG_PATH=${BREW_PREFIX}/lib/pkgconfig:${BREW_PREFIX}/opt/curl/lib/pkgconfig:${BREW_PREFIX}/opt/fmt/lib/pkgconfig
export CMAKE_PREFIX_PATH=${BREW_PREFIX}
export LDFLAGS=-L${BREW_PREFIX}/lib
export CPPFLAGS=-I${BREW_PREFIX}/include
- Build
cmake .. \
-DWITH_MPRIS=OFF \
-DCMAKE_BUILD_TYPE=Release \
-DCMAKE_PREFIX_PATH="${HOMEBREW_PREFIX}"
cmake --build . --config Release -j$(nproc 2>/dev/null || sysctl -n hw.ncpu 2>/dev/null || echo 2)
MISC Build, Compile & Install
mkdir build && cd build
cmake .. # -DWITH_MPRIS=OFF -DWITH_CAVA=ON
make
sudo make install
Configure MCP
Use tuisic --mcp-server command in your ai client config.
Example in .config/opencode/opencode.json:
"tuisic":{
"type": "local",
"command": ["/path/to/tuisic/build/tuisic", "--mcp-server"],
"enabled": true
}
DEMOS
- Screenshots: here scroll way down.
- Visualizer:
https://github.com/user-attachments/assets/1f512307-7c70-466d-9cd0-529e195871d0
- MCP Server:
https://github.com/user-attachments/assets/7601312a-9bca-4970-90a3-4a917fbe2fda
- Discord Rich Presence:
Thanks to all.
Contribution
It's open for contribution, read CONTRIBUTING.md for more information.
Tuisic MCP questions
How do I configure the Tuisic MCP server in my AI client?
Run the tuisic binary with the --mcp-server flag and add it as a local command in your client config.
Which music sources can Tuisic search?
Tuisic fetches songs from JioSaavn, SoundCloud, LastFM, ForestFM, and YouTube, with YouTube Music planned.
Does Tuisic support playing local music files?
Yes, selecting Local Music scans the configured local_music.path recursively and plays files through mpv.
How do I install Tuisic on Arch Linux?
Install the tuisic-git package from the AUR with yay, or build from source with the listed dependencies.
What keyboard shortcuts does Tuisic have?
It uses vim-style motions: q quits, w toggles daemon mode, space plays or pauses, and > and < skip tracks.