tuisic

TUISIC is a local, non-web MCP-enabled music player that can interact with MCP-enabled AI clients. The server component is activated by running the tuisic executable with the --mcp-server flag, which starts an MCP interface so AI clients can request song data, control playback, and retrieve metadata through the MCP protocol. Once the server is running, you can configure your MCP client to connect to it (for example in your client’s .config/opencode/opencode.json) by pointing to the local binary and enabling the local mode, as shown in the README example. The MCP integration enables AI-assisted search, playback control, and data exchange between your CLI music player and AI services, allowing you to issue natural-language-like commands to discover and play songs.

In practice, your MCP-enabled TUisIC setup supports commands and events such as querying for tracks, starting playback, pausing, seeking, and retrieving lyrics or metadata via the MCP channel. To use it, start tuisic with --mcp-server, then configure your MCP client to connect to the local address/port you expose. The client will send requests (e.g., search for a track, add to playlist, control playback) and TUisIC will respond with results or action confirmations. This enables automation and AI-assisted music discovery directly from your MCP-enabled AI workflows.

Prerequisites:

• A modern CMake-based build environment (cmake, a C/C++ compiler, standard development tools)
• Basic system dependencies as listed in the TUisIC README (dependent on platform)

Install steps:

1. Install build tools (example for Debian/Ubuntu):

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

2. Clone the repository (or download a source release):

git clone https://github.com/Dark-Kernel/tuisic.git
cd tuisic

3. Build from source (example, adjust flags as needed):

cmake .. -DCMAKE_BUILD_TYPE=Release
cmake --build . --config Release -j$(nproc 2>/dev/null || sysctl -n hw.ncpu 2>/dev/null || echo 2)

4. (Optional) Install system-wide:

sudo cmake --build . --target install

5. Run MCP server:

tuisic --mcp-server

6. Configure your MCP client to connect to the local TUisIC MCP server as shown in the README example (path to the built binary and --mcp-server flag).

If you prefer packaged builds, you can follow the installation steps in the README for using AUR or other packaging systems, then run the binary with the same --mcp-server option.

Tips and considerations:

• The MCP server is exposed by running the tuisic binary with --mcp-server. Ensure the executable has the proper permissions and is in your PATH or specify the full path in your MCP client configuration.
• You can customize connection details via environment variables (for example, TUISIC_MCP_PORT or TUISIC_MCP_TOKEN) if you need to secure or scope access to the MCP interface.
• If you enable MPRIS or other features during build, ensure their dependencies are installed (e.g., sdbus-cpp for MPRIS on Linux).
• When building on macOS or Linux, follow platform-specific instructions from the README to set up dependencies and environment variables before running the build.
• The MCP integration is beta; expect occasional changes in the MCP contract or client configuration examples as the project evolves.