easyeffects-mcp

An MCP server that lets AI assistants (Claude Code, Claude Desktop, Cursor, VS Code, etc.) control Easy Effects, the PipeWire audio effects app for Linux.

Ask things like:

• "Turn off all my audio effects" / "turn them back on"

• "Load my headphones preset"

• "Boost the bass a bit on my EQ"

• "Apply this AutoEQ profile for my HD 600s: …"

• "What plugins are active on my mic?"

Requirements

• Linux with Easy Effects running (native package or Flatpak)

• uv (it installs Python 3.10+ for you if needed)

Check your version with easyeffects --version (or flatpak run com.github.wwmm.easyeffects --version).

Related MCP server: Twill

Install

You don't need to clone anything. Point your MCP client at:

uvx --from git+https://github.com/kaushikgunasekaren/easyeffects-mcp easyeffects-mcp

Claude Code

claude mcp add easyeffects --scope user -- uvx --from git+https://github.com/kaushikgunasekaren/easyeffects-mcp easyeffects-mcp

Claude Desktop, Cursor, Windsurf and other JSON-configured clients

{
  "mcpServers": {
    "easyeffects": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/kaushikgunasekaren/easyeffects-mcp", "easyeffects-mcp"]
    }
  }
}

VS Code (.vscode/mcp.json)

{
  "servers": {
    "easyeffects": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/kaushikgunasekaren/easyeffects-mcp", "easyeffects-mcp"]
    }
  }
}

uvx caches the install. To pick up a newer version, run uv cache clean easyeffects-mcp and restart your client.

Tools

output is the speakers/headphones pipeline, input is the microphone pipeline. Property names are the camelCase keys Easy Effects stores in ~/.config/easyeffects/db/*rc (e.g. inputGain, band3Gain, bypass).

Limitations

• Adding or removing plugins from the chain isn't exposed by Easy Effects' control socket. Do that in the app, or save a preset with the plugins you want and load it.

• Live property changes aren't saved into a preset until you save it in Easy Effects.

Troubleshooting

"control socket not found": Easy Effects isn't running. Start it in the background with easyeffects --service-mode -w (Flatpak: flatpak run com.github.wwmm.easyeffects --service-mode -w). Enabling "Launch on system startup" in its settings keeps it running.

"error_plugin_not_found": that plugin isn't in the chain. Ask for get_status to see which plugins are loaded, and add the plugin in the Easy Effects window.

Socket in an unusual place: set EASYEFFECTS_SOCKET to its path in your MCP client's env block.

Development

git clone https://github.com/kaushikgunasekaren/easyeffects-mcp.git
cd easyeffects-mcp
uv sync
uv run pytest
npx @modelcontextprotocol/inspector uv run easyeffects-mcp   # MCP Inspector

License

MIT