sonilo-mcp 0.1.0

MCP server for Sonilo AI music generation API

Sonilo MCP Server

An MCP (Model Context Protocol) server that exposes Sonilo's AI music generation API to MCP-compatible clients (Claude Desktop, Cursor, etc.).

Install

uvx sonilo-mcp

Or install with pip:

pip install sonilo-mcp

Audio Playback Dependencies

The play_audio tool requires PortAudio at runtime (for sounddevice). On macOS/Linux, install via:

• macOS: brew install portaudio
• Debian/Ubuntu: sudo apt-get install libportaudio2

uvx sonilo-mcp and pip install will pull the Python bindings, but the system PortAudio library must be installed separately. The other tools (text_to_music, video_to_music, get_account_services, get_usage) work without PortAudio.

Configuration

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "sonilo": {
      "command": "uvx",
      "args": ["sonilo-mcp"],
      "env": {
        "SONILO_API_KEY": "sk_live_..."
      }
    }
  }
}

Get your API key at https://platform.sonilo.com/dashboard/api-keys.

Codex

Add the server to ~/.codex/config.toml:

[mcp_servers.sonilo]
command = "uvx"
args = ["sonilo-mcp"]

[mcp_servers.sonilo.env]
SONILO_API_KEY = "sk_live_..."

Restart Codex (or start a new session) to load it, then run /mcp to confirm sonilo is connected and its tools are listed.

Environment Variables

Variable	Default	Description
SONILO_API_KEY	(required)	Bearer token.
SONILO_API_URL	https://api.sonilo.com	Public API base URL.
SONILO_MCP_BASE_PATH	~/Desktop	Default output directory and base for relative input paths. Also the confinement boundary (see below).
SONILO_MCP_ALLOW_ANY_PATH	false	Set to true to let tools read/write files outside SONILO_MCP_BASE_PATH.
TIME_OUT_SECONDS	300	Generation timeout.

File access & confinement

By default, the file tools (video_to_music input, play_audio, and any output_directory) are confined to SONILO_MCP_BASE_PATH. Paths that resolve outside it (after symlink resolution) are rejected. This limits the blast radius if a client is tricked into reading or exfiltrating arbitrary files. To opt out — e.g. to read a video from elsewhere on disk — set SONILO_MCP_ALLOW_ANY_PATH=true.

Tools

Tool	Description	Cost
text_to_music(prompt, duration, output_directory?)	Generate music from a text prompt.	✅
video_to_music(video_path? | video_url?, prompt?, output_directory?)	Generate music matched to a video.	✅
get_account_services()	List available services and limits.	❌
get_usage(days=30)	Show usage summary + per-day breakdown.	❌
play_audio(input_file_path)	Play a local audio file.	❌

Tools marked ✅ make API calls that incur charges on your Sonilo account.

Output Format

Generated audio is saved as .m4a (AAC in MP4 container — this is what the backend currently emits). File names use the title returned by the backend (slugified) or a sonilo-<timestamp>.m4a fallback. When multiple parallel streams are returned, a -<index> suffix is appended.

Common Errors

Message	What to do
Invalid SONILO_API_KEY	Verify the key at https://platform.sonilo.com/dashboard/api-keys.
Insufficient minutes / Credit limit exceeded	Top up at https://platform.sonilo.com/dashboard/billing.
Rate limit exceeded	Check get_account_services for your rpm/concurrency limits.
Generation timed out	Raise TIME_OUT_SECONDS. Check get_usage to confirm whether the backend completed and charged.

Development

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest

License

MIT