Liquidsoapmcp

🚀 LiquidSoap MCP Server

Provide accurate Liquidsoap 2.4.0 documentation, examples, and script validation for AI assistants through the Model Context Protocol.

Large Language Models (LLMs) often make mistakes with Liquidsoap, mixing 1.x documentation, outdated blog posts, and half - remembered API examples. This MCP server solves this problem by providing your AI assistant (such as Claude, ChatGPT, Cursor, Windsurf, etc.) with real Liquidsoap 2.4.0 documentation, examples, and API references. This enables the following:

• Understand .liq scripts.
• Generate correct 2.4.0 code.
• Fix errors and deprecated usage.
• Explore operators, functions, transitions, and patterns.
• Build web radio pipelines with confidence.

There are no hallucinations, no version drift, and no mystery errors.

🚀 Quick Start

LLMs frequently err in handling Liquidsoap. This MCP server addresses these issues by offering accurate Liquidsoap 2.4.0 resources to your AI assistant, enabling reliable Liquidsoap scripting.

✨ Features

Version - Pinned Documentation (2.4.0)

• Full language reference.
• Core API functions & operators.
• Protocols (Icecast, HLS, HTTP, SRT, etc.).
• Encoder/decoder options.
• Runtime settings.

Smart Search

• Search functions/operators by name or keyword.
• Search through examples, patterns, and cookbook items.
• Search 2.4.0 changelog & migration notes.

Script Assistance

• Detect deprecated functions (e.g., null(), insert_metadata).
• Warn about 1.x syntax.
• Highlight common design pitfalls.

Example Library

Ready - to - use snippets for:

• Crossfading.
• Fallback chains.
• Harbor live input.
• HLS output.
• Cron scheduling (cron.add, cron.parse).
• Metadata rewriting.
• LUFS normalization.
• Blank detection.
• Multi - output pipelines.

Fast & Local

• Docs cached and indexed for instant responses.
• No web requests needed once running.

📦 Installation

Prerequisites

• Node.js ≥ 18
• Any MCP - compatible client

Install via npm (recommended)

npm install -g liquidsoap-mcp-server

Or run from source

git clone https://github.com/splinesreticulating/LiquidSoapMCP.git
cd LiquidSoapMCP
npm install
npm run build

💻 Usage Examples

Claude Desktop Example

macOS:
~/Library/Application Support/Claude/claude_desktop_config.json

Windows:
%APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "liquidsoap": {
      "command": "npx",
      "args": ["-y", "liquidsoap-mcp-server"]
    }
  }
}

From source:

{
  "mcpServers": {
    "liquidsoap": {
      "command": "node",
      "args": ["/absolute/path/to/LiquidSoapMCP/build/index.js"]
    }
  }
}

Docker:

{
  "mcpServers": {
    "liquidsoap": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "liquidsoap-mcp-server"]
    }
  }
}

Build the image:

docker build -t liquidsoap-mcp-server .

📚 Documentation

Supported Tools

Core Tools

• get_version
• list_sections
• get_documentation(section)
• search_functions(query)
• get_changelog
• get_examples(topic)
• validate_script_syntax(script)

Documentation Sections

• language
• reference
• protocols
• settings
• encoding_formats
• ffmpeg
• quickstart
• cookbook

Roadmap

• [ ] Liquidsoap script graph visualization
• [ ] Integrate liquidsoap --check for full type validation
• [ ] Multi - version switching (2.2.x, 2.3.x, etc.)
• [ ] Fuzzy search & semantic function lookup
• [ ] “Explain this error log” tool
• [ ] Pattern/snippet library

Contributing

PRs are welcome, especially for:

• More examples
• Better search
• Doc parsing improvements
• Additional validation rules
• MCP integration templates

Resources

• https://www.liquidsoap.info/doc-2.4.0/
• https://modelcontextprotocol.io/
• https://github.com/modelcontextprotocol/typescript-sdk

Acknowledgments

This project is built for the Liquidsoap community, including DJs, web - radio operators, self - hosters, and audio enthusiasts, aiming to make Liquidsoap easier, safer, and more fun with AI assistance.

Want to support the project?

Please star the repo! It helps others discover it and indicates that this niche is worth exploring.