LiquidSoap MCP Server

Version-accurate Liquidsoap scripting using the official 2.4.0 docs.

LLMs get Liquidsoap wrong a lot. Mixing 1.x docs, outdated blog posts, and half-remembered API examples.

This MCP server fixes that.

It gives your AI assistant (Claude, ChatGPT, Cursor, Windsurf, etc.) real Liquidsoap 2.4.0 documentation, examples, and API references, making it finally possible to:

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

No hallucinations. No version drift. No mystery errors.

Why this exists

Liquidsoap is incredibly powerful, but:

Documentation varies heavily between versions
1.x and 2.x syntax differs in subtle ways
LLMs blend outdated examples into their answers
Even the official docs are spread across sections, pages, and changelogs

This MCP server gives your AI one job:
Stick to Liquidsoap 2.4.0 exactly.

It exposes a clean, structured API around the official docs so your assistant becomes a reliable Liquidsoap expert.

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:

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

Demo (example)

Ask:

“Explain what this Liquidsoap script does.”
“Add a fallback before the HLS output.”
“Show the docs for crossfade.”
“Fix deprecated functions in this script.”
“Rewrite this using Liquidsoap 2.4.0-style null.”

Your AI responds using only the pinned 2.4.0 docs.

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

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 .

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 welcome. Especially:

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

Built for the Liquidsoap community, and for the DJs, webradio operators, self-hosters, and audio nerds who want Liquidsoap to be easier, safer, and more fun with AI assistance.

Want to support the project?

Please star the repo!
It helps others discover it and tells me this niche was worth carving out.

MCP Servers