SoX MCP Server

A Model Context Protocol (MCP) server that provides powerful audio inspection and processing capabilities to LLM agents. This server wraps the SoX (Sound eXchange) command-line utilities, allowing AI agents to "hear" and manipulate audio files through structured JSON interfaces.

🚀 Features

Agents can use this server to perform a wide range of audio tasks:

• Inspection: Get detailed metadata (duration, sample rate, channels, bitrate, format, encoding) and statistical analysis (RMS, peak level, etc.) from audio files.
• Conversion: Convert audio between formats (e.g. WAV to MP3).
• Processing:
  • Resample audio to different sample rates.
  • Adjust volume, normalize peaks, or apply gain.
  • Trim audio or remove silence (VAD).
  • Remix or swap audio channels.
  • Concatenate or mix multiple audio files.
  • Apply a vast array of SoX effects (reverb, equalizer, delay, etc.).
• Generation: Generate pure sine tones, white noise, or silence for testing.
• Discovery: List audio files within a directory with optional extension filtering.

📋 Prerequisites

1. Python 3.10+
2. SoX Utilities: You must have the sox and soxi executables installed on your system and available in your PATH.
   • Windows: Download from sox.sourceforge.net or install via choco install sox.
   • macOS: brew install sox
   • Linux: sudo apt-get install sox libsox-fmt-all

🛠️ Installation

1. Clone the repository

git clone <repository-url>
cd sox-mcp-server

2. Set up a Virtual Environment

python -m venv .venv
# On Windows:
.venv\Scripts\activate
# On macOS/Linux:
source .venv/bin/activate

3. Install Dependencies

pip install -r requirements.txt

---

💻 Development

Running the Server

The server uses the MCP standard I/O transport. To run it manually for debugging:

python sox_mcp_server.py

Testing

We provide a smoke test script to verify the server and its connection to the SoX binaries:

# Ensure you are in your virtual environment
python test_smoke.py

Environment Variables

If sox or soxi are not in your system PATH, you can specify their location using the SOX_PATH environment variable.

---

🤖 Integration

Claude Desktop

To use this server with the Claude Desktop app, add it to your configuration file.

Config Location:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Configuration Example:

{
  "mcpServers": {
    "sox-mcp": {
      "command": "C:\\path\\to\\your\\project\\.venv\\Scripts\\python.exe",
      "args": [
        "C:\\path\\to\\your\\project\\sox_mcp_server.py"
      ],
      "env": {
        "SOX_PATH": "C:\\Program Files\\sox\\sox.exe"
      }
    }
  }
}

Note: Use absolute paths for the python executable and the server script. If sox is not in your system PATH, use the SOX_PATH environment variable as shown above.

LM Studio

LM Studio supports MCP servers. To add this server:

1. Open LM Studio.
2. Navigate to the MCP section in the settings/sidebar.
3. Click Add Server (or equivalent depending on your version).
4. Select Command/Stdio as the connection type.
5. Enter the following:
   • Command: The path to your .venv\Scripts\python.exe.
   • Arguments: The absolute path to sox_mcp_server.py.
6. Click Save/Connect.

---

🛠️ Tool List

Tool	Description
audio_info	Get complete metadata for one or more files.
list_files	List files in a directory with optional extension filtering.
convert_audio	Convert audio formats and change bit depth.
resample	Change the sample rate of an audio file.
remix_channels	Merge, split, or swap audio channels.
trim_audio	Trim time ranges or auto-trim silence.
adjust_volume	Normalize or adjust gain (dB).
concatenate_audio	Append, merge, or mix multiple files.
apply_effect	Apply any SoX effect (reverb, EQ, etc.).
audio_stats	Compute RMS, peak, and other playback statistics.
generate_tone	Generate test tones or noise files.