AudacityMCP

AudacityMCP conecta cualquier asistente de IA compatible con MCP a Audacity, dándole control total sobre la edición de audio a través de 144 herramientas que abarcan efectos, limpieza, masterización, transcripción y más. Habla con tu asistente de IA y este edita tu audio en tiempo real.

Sin nube. Sin claves de API para el procesamiento de audio. Todo se ejecuta localmente a través de la interfaz de pipe con nombre de Audacity.

Si esto te resulta útil, una estrella ayuda a que otras personas lo encuentren — ese es todo el presupuesto de marketing de este proyecto. ¿Quieres ayudar a mantenerlo? Haz clic en la insignia Sponsor de arriba.

Compatibilidad: AudacityMCP actualmente funciona solo con Audacity 3.x. Audacity 4.x aún no es compatible; esperamos agregar soporte en el futuro.

Funciona con

AudacityMCP funciona con cualquier cliente de IA que admita el Model Context Protocol:

• Claude Desktop — la aplicación de escritorio de Anthropic

• Claude Code — agente CLI

• Cursor — editor de código con IA con soporte MCP

• Cualquier otro cliente compatible con MCP

Inicio rápido

1. Obtén AudacityMCP

Opción A: Haz clic en el botón verde Code de arriba → Download ZIP → extrae a una carpeta

Opción B: Clona con git:

git clone https://github.com/xDarkzx/Audacity-MCP.git

2. Ejecuta el instalador (configura todo lo demás automáticamente)

Windows: haz doble clic en install.bat en el Explorador de archivos o, si ya estás en una terminal desde el paso de git clone anterior, simplemente continúa en la misma ventana de PowerShell/Command Prompt:

cd Audacity-MCP
.\install.bat

macOS / Linux:

cd Audacity-MCP
bash install.sh

El instalador hace 3 cosas: instala audacity-mcp desde esta carpeta local (la que acabas de descargar/clonar, sin descargas de PyPI ni GitHub), habilita mod-script-pipe en Audacity y configura Claude Desktop — no se necesita edición manual de JSON. Pide confirmación antes de tocar cualquiera de los archivos de configuración, explica exactamente lo que va a hacer primero y siempre hace una copia de seguridad de un archivo existente antes de modificarlo. ¿Quieres ver todo lo que haría sin cambiar nada? Añade --dry-run: .\install.bat --dry-run / bash install.sh --dry-run.

Nota: install.bat/install.sh deben ejecutarse desde dentro de esta carpeta; solo instalan el código que está justo al lado, no descargan nada por sí mismos.

Si no usas Claude Desktop, instala manualmente con pip install audacity-mcp-server y añádelo a la configuración MCP de tu cliente:

{
  "mcpServers": {
    "audacity": {
      "command": "audacity-mcp"
    }
  }
}

Consulta la documentación MCP de tu cliente para conocer la ubicación del archivo de configuración.

¿El cliente no puede encontrar/ejecutar audacity-mcp? Las aplicaciones GUI no siempre ven el mismo PATH que una terminal. Ejecuta python -c "import sysconfig; print(sysconfig.get_path('scripts'))" y usa la ruta completa que imprima (más \audacity-mcp.exe en Windows o /audacity-mcp en macOS/Linux) como "command" en lugar del nombre simple.

Sin install.bat/install.sh, nada toca tu sistema automáticamente: tres pasos, todos hechos a mano:

1. Habilita mod-script-pipe en Audacity: Editar → Preferencias (Windows/Linux) o Audacity → Preferencias (macOS) → Módulos → establece mod-script-pipe en Habilitado → Aceptar → reinicia Audacity.

2. Instala el paquete: abre una terminal (Command Prompt/PowerShell en Windows, Terminal en macOS/Linux) y ejecuta pip install audacity-mcp-server — una instalación normal de PyPI, sin necesidad de clonar el repositorio.

3. Configura Claude Desktop: abre Claude Desktop → Configuración (icono de engranaje) → pestaña Desarrollador → Editar configuración — esto abre claude_desktop_config.json en un editor de texto. Añade esto dentro del bloque "mcpServers", conservando cualquier otro servidor que ya tengas:

   {
     "mcpServers": {
       "audacity": {
         "command": "audacity-mcp"
       }
     }
   }

   Guarda el archivo y reinicia completamente Claude Desktop (sal de la bandeja del sistema, no solo cierres la ventana).

Esa es toda la instalación; consulta la Guía de instalación para ver los mismos pasos con más detalle y notas por sistema operativo.

¿"audacity" no aparece como herramienta después de reiniciar? El "command": "audacity-mcp" anterior solo funciona si ese comando está en el mismo PATH que usa Claude Desktop, lo cual no siempre es el caso (especialmente si Claude Desktop ya estaba abierto cuando instalaste Python). Si no se conecta, ejecuta esto en una terminal para encontrar la ubicación real de instalación: python -c "import sysconfig; print(sysconfig.get_path('scripts'))" — luego reemplaza "audacity-mcp" arriba con la ruta completa que imprima más \audacity-mcp.exe (Windows, recuerda duplicar cada barra invertida: \\) o /audacity-mcp (macOS/Linux).

3. Empieza a editar

Abre Audacity, carga algo de audio y luego habla con tu IA:

"Clean up this podcast recording"
"Master this track for Spotify, it's EDM"
"Transcribe this and add labels at each sentence"
"Add reverb with a large room, then export as FLAC"

Audacity debe estar abierto primero. AudacityMCP se comunica a través del pipe con nombre de Audacity; no puede iniciar Audacity por ti.

Consulta la Guía de instalación completa para una configuración detallada en todas las plataformas y clientes MCP.

Related MCP server: ReaperMCP

¿Por qué AudacityMCP?

Sin AudacityMCP: Navegas manualmente por los menús, ajustas los parámetros de los efectos de oído, aplicas efectos uno a la vez, buscas especificaciones ACX y repites hasta que suene bien.

Con AudacityMCP: Describes lo que quieres en lenguaje natural y la IA se encarga del resto: elegir los efectos correctos, establecer parámetros estándar de la industria y encadenar operaciones.

AudacityMCP es especialmente útil para:

• Podcasters que quieren un sonido consistente y profesional sin conocimientos de ingeniería de audio

• Músicos que necesitan una masterización rápida con ajustes apropiados para el género

• Creadores de contenido que trabajan con entrevistas, locuciones o grabaciones de campo

• Cualquiera que prefiera describir lo que quiere en lugar de hacer clic en menús

¿Qué puede hacer?

You:  "Clean up this podcast recording"
AI:   Runs auto_cleanup_podcast → HPF 80Hz → noise reduction → compression → safe loudness check

You:  "Master this track for Spotify, it's EDM"
AI:   Runs auto_master_music style=edm → HPF 30Hz → click removal → compression 2.5:1 → bass +2dB → loudness check

You:  "This is a noisy live recording, fix it up"
AI:   Runs auto_cleanup_live → HPF 100Hz → click removal → noise reduction 18dB → compression 5:1

You:  "Transcribe this interview and add labels"
AI:   Runs transcribe_to_labels → faster-whisper transcription → Audacity labels at each timestamp

You:  "Add reverb to the vocals, then export as FLAC"
AI:   select region → reverb effect → export to FLAC

Características

144 herramientas en 11 categorías

Pipelines

AudacityMCP incluye 9 pipelines de un clic para tareas de audio comunes. Cada pipeline está diseñado para ser seguro con audio mal grabado — nunca aumentará tu audio de forma peligrosa. Los pipelines limpian y mejoran tu audio, y luego puedes ajustar manualmente el volumen si es necesario.

Cómo funcionan los pipelines

1. Le dices a la IA lo que quieres (p. ej., "limpia este podcast")

2. La IA elige el pipeline adecuado y lo inicia

3. El pipeline se ejecuta en segundo plano: recibes un job_id de vuelta

4. Consulta con check_pipeline_status cada 15-30 segundos para monitorear el progreso

5. Cuando termina, aparece una ventana emergente en Audacity

Regla de seguridad: Los pipelines solo reducen los picos si están demasiado altos. Nunca aumentan el volumen. Si quieres alcanzar un objetivo específico de LUFS (p. ej., -14 para Spotify), pide a la IA que ejecute loudness_normalize después de comprobar que los resultados se ven bien.

Referencia de pipelines

auto_analyze_audio — Analizar antes de procesar

Mide tu audio y recomienda el mejor pipeline. Ejecuta esto primero si no estás seguro de qué hacer.

You: "Analyze this audio"
→ Returns: peak level, noise floor, clipping status, recommended pipeline

auto_cleanup_audio — Limpieza segura solamente

Limpia ruido y artefactos sin cambiar el volumen en absoluto. Úsalo cuando los niveles ya estén bien.

You: "Just clean up the noise, don't change the volume"
→ DC offset removal → HPF 80Hz → noise reduction → click removal (optional)

auto_cleanup_podcast — Podcast / voz en off

Procesamiento profesional de radiodifusión para voz hablada.

You: "Clean up this podcast recording"
→ DC offset → HPF 80Hz → noise reduction 12dB → compression 3:1 → safe loudness check

auto_audiobook_mastering — Audiolibro (ACX/Audible)

Cumple los requisitos de ACX para la distribución de audiolibros.

You: "Master this for ACX / Audible"
→ DC offset → HPF 80Hz → noise reduction 12dB → compression 2.5:1 → safe loudness check → peak cap -3dB

auto_cleanup_interview — Entrevista / diálogo

Toque ligero para conversaciones: preserva la dinámica natural.

You: "Clean up this interview recording"
→ DC offset → HPF 80Hz → noise reduction 8dB → compression 2.5:1 → safe loudness check

auto_cleanup_vocal — Canto / voz de estudio

Ajustado para grabaciones vocales con EQ de presencia para mayor claridad.

You: "Process this vocal recording"
→ DC offset → HPF 100Hz → noise reduction 10dB → compression 3:1 → presence EQ (+3dB treble, -1dB bass) → safe loudness check

auto_cleanup_live — En vivo / campo / grabación ruidosa

Limpieza agresiva para entornos ruidosos. Los primeros 0,5 s deben ser ruido ambiental para el perfilado.

You: "This is a noisy live recording, clean it up"
→ DC offset → HPF 100Hz → click removal → noise reduction 18dB → compression 5:1 → safe loudness check

auto_master_music — Masterización de música

Masterización ajustada por género con 6 preajustes: edm, hiphop, rock, pop, classical, acoustic.

You: "Master this hip-hop track"
→ HPF 30Hz → click removal → compression 2:1 → bass +3dB treble +1dB → safe loudness check

You: "Master this for a classical album"
→ HPF 30Hz → click removal → compression 1.3:1 (very gentle) → no EQ → safe loudness check

auto_lofi_effect — Lo-fi creativo / vintage

Aplica un sonido lo-fi cálido y vintage. Preajustes: light, medium, heavy.

You: "Give this a lo-fi vibe"
→ HPF → LPF (muffled highs) → bass/treble warmth → compression 2:1 → safe loudness check

Después de un pipeline: ajustar el volumen

Los pipelines dejan el volumen intacto a propósito (solo reducen si los picos están recortando). Para alcanzar un objetivo de streaming:

You: "Now normalize this to -14 LUFS for Spotify"
→ AI uses loudness_normalize tool with lufs_level=-14

You: "Normalize to -16 LUFS for podcast"
→ AI uses loudness_normalize tool with lufs_level=-16

¿Por qué no hacerlo automáticamente? La normalización LUFS puede aumentar el audio silencioso o mal grabado en 10-20 dB, lo que lo satura. Al separar la limpieza del volumen, puedes comprobar los resultados antes del paso final de volumen.

Transcripción local (Experimental)

Esta función es experimental y requiere una configuración aparte. Todo lo demás funciona sin ella.

Desarrollado por faster-whisper — se ejecuta completamente sin conexión, tu audio nunca sale de tu máquina:

• 5 tamaños de modelo: tiny, base, small, medium, large-v3

• Transcribe audio completo o solo una selección

• Exporta como subtítulos SRT, VTT o texto plano

• Añade automáticamente etiquetas de Audacity en cada segmento hablado

• Detección de idioma o especifica más de 99 idiomas

Configuración necesaria antes del primer uso: Consulta Configuración de transcripción para los pasos de instalación.

¿Quieres aceleración por GPU (10-20 veces más rápida)? Ejecuta audacity-mcp-setup-gpu — o descarga setup_gpu.bat/setup_gpu.sh y haz doble clic/ejecútalo si prefieres no usar una terminal. Detecta tu GPU, instala lo necesario y verifica que realmente funciona. Solo GPUs NVIDIA (las gráficas AMD/Intel y macOS no son compatibles con el backend de transcripción en absoluto: cualquier tarjeta NVIDIA funciona, GeForce no es un requisito, solo tener una GPU NVIDIA). ¿No tienes GPU NVIDIA? La CPU funciona bien, solo más lenta en archivos largos.

¿El script dice que funcionó pero la transcripción sigue lenta/en CPU? Eso significa que Claude Desktop está lanzando audacity-mcp desde un Python diferente al que el script acaba de verificar: consulta la solución (una edición manual de configuración, cinco minutos).

Novedades — v0.1.3

32 nuevas herramientas (99 → 131), correcciones de ajuste de pipelines y probado en vivo con Audacity.

• Nuevos efectos: Reverse, Invert, Repair, AutoDuck, NotchFilter, VocalReduction, AdjustableFade, StudioFadeOut, CrossfadeClips, CrossfadeTracks, ClipFix, SlidingStretch, Tremolo

• Nueva edición: Split (en el lugar), SplitCut, SplitDelete, Disjoin + el antiguo split renombrado → edit_split_new

• Nuevas pistas: StereoToMono, MixAndRenderToNew, MuteAll, UnmuteAll, Resample, AlignEndToEnd, AddLabelTrack

• Nueva selección: CursorToTrackStart/End, CursorToProjectStart/End, SelectCursorToTrackEnd

• Nuevo proyecto: EditMetadata, ImportMIDI

• Nuevas etiquetas: RegularIntervalLabels

• Correcciones de pipelines: límite de pico ACX -3.0→-3.5dB, NR en vivo 18→12dB, comp de podcast 10ms/1s→30ms/200ms, liberación de entrevista 1s→200ms

• Corrección de errores: effect_repair ahora usa un tiempo de espera largo (Audacity muestra una ventana emergente en selección no válida)

• Validación: Se añadieron comprobaciones de rango faltantes en AutoDuck, VocalReduction, SlidingStretch, Resample

Solución de problemas

mod-script-pipe no habilitado

El instalador habilita esto automáticamente, pero si no funcionó (p. ej., Audacity nunca se abrió antes), habilítalo manualmente:

1. Abre Audacity

2. Ve a Editar → Preferencias (Windows/Linux) o Audacity → Preferencias (macOS)

3. Haz clic en Módulos en la barra lateral izquierda

4. Establece mod-script-pipe en Habilitado

5. Haz clic en Aceptar y reinicia Audacity

Problemas de conexión

Problemas con los pipelines

Consejos de calidad de audio

Problemas generales

Arquitectura

┌──────────────┐     stdio      ┌──────────────┐   named pipe   ┌──────────────┐
│  MCP Client  │◄──────────────►│ AudacityMCP  │◄──────────────►│   Audacity   │
│(AI assistant)│    (JSON-RPC)  │   FastMCP    │  (commands)    │              │
└──────────────┘                └──────────────┘                └──────────────┘
                                       │
                                       ├── audacity_mcp/main.py          (entry point)
                                       ├── audacity_mcp/audacity_client.py (pipe I/O)
                                       ├── audacity_mcp/tool_registry.py  (auto-loader)
                                       └── audacity_mcp/tools/            (11 modules)

Decisiones de diseño clave

• Pipes con nombre, no TCP — IPC directo al mod-script-pipe de Audacity. Sin exposición a la red, sin conflictos de puertos.

• Cero exec/eval — Cada operación se asigna a un manejador estático con validación de entrada. Sin ejecución de código arbitrario.

• Multiplataforma — Windows usa la API Win32 mediante ctypes, Unix usa E/S de archivos estándar.

• Asíncrono en todo — Todos los manejadores de herramientas son async. La E/S de pipes bloqueante se ejecuta en un grupo de ejecutores con tiempos de espera configurables.

• Pipelines seguros — Los pipelines miden el audio antes de tomar decisiones de sonoridad. Solo reducen, nunca aumentan.

• Registro dinámico de herramientas — Coloca un módulo en audacity_mcp/tools/, exporta una función register(mcp) y se descubre automáticamente.

Estructura del proyecto

AudacityMCP/
├── audacity_mcp/
│   ├── main.py                 # FastMCP server entry point
│   ├── audacity_client.py      # Cross-platform named pipe client
│   ├── tool_registry.py        # Auto-discovers and registers tool modules
│   └── tools/
│       ├── analysis_tools.py   # Audio analysis (contrast, spectrum, beats)
│       ├── cleanup_tools.py    # Noise reduction, mastering, 9 pipelines
│       ├── edit_tools.py       # Cut, copy, paste, split, join, trim
│       ├── effects_tools.py    # Reverb, echo, pitch, EQ, filters
│       ├── generate_tools.py   # Tone, noise, chirp, DTMF generation
│       ├── label_tools.py      # Label management
│       ├── project_tools.py    # Project/file operations
│       ├── selection_tools.py  # Selection and cursor control
│       ├── track_tools.py      # Track management
│       ├── transcription_tools.py  # Whisper-based transcription
│       └── transport_tools.py  # Playback and recording control
├── audacity_mcp_shared/
│   ├── constants.py            # Pipe paths, timeouts, allowed formats
│   ├── error_codes.py          # Typed error codes (pipe/command/validation)
│   └── pipe_protocol.py        # Command formatting and response parsing
├── tests/                      # 60 tests
├── docs/
│   ├── INSTALLATION.md         # Detailed setup guide
│   └── TOOLS.md                # Complete tool reference
└── pyproject.toml

Desarrollo

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -x -q

# Run lint (real bugs + security patterns, not style/formatting)
ruff check .

Añadir nuevas herramientas

1. Crea un módulo en audacity_mcp/tools/ (o añádelo a uno existente)

2. Exporta una función register(mcp: FastMCP)

3. Define tus herramientas con decoradores @mcp.tool()

4. Eso es todo: el registro de herramientas lo descubre automáticamente al inicio

# audacity_mcp/tools/my_tools.py
from mcp.server.fastmcp import FastMCP
from audacity_mcp_shared.error_codes import AudacityMCPError, ErrorCode


def register(mcp: FastMCP):
    from audacity_mcp.main import client

    @mcp.tool()
    async def my_custom_effect(intensity: float = 0.5) -> dict:
        """Apply my custom effect to the selected audio."""
        if not 0 <= intensity <= 1:
            raise AudacityMCPError(ErrorCode.VALUE_OUT_OF_RANGE, "intensity must be 0-1")
        return await client.execute_long("MyEffect", Intensity=intensity)

Consulta CONTRIBUTING.md para las pautas completas.

Comunidad

Convertir esto en una herramienta que todo usuario de Audacity quiera usar requiere más de una persona. Si estás usando AudacityMCP, aunque solo sea para probarlo, únete al Discord: comparte lo que has construido, informa de lo que está roto, sugiere lo que falta, o simplemente pasa el rato con otras personas que hacen edición de audio impulsada por IA. Las comunidades crecen cuando una persona le cuenta a otra que esto existe, así que si conoces a alguien que podría beneficiarse de esto, envíale el enlace.

Soporte

Si AudacityMCP te ha ahorrado tiempo o te ha ayudado con tus proyectos de audio, considera patrocinar:

Tu apoyo ayuda a mantener este proyecto y a que sea gratuito para todos.

Documentación

• Guía de instalación — Configuración detallada para Windows, macOS y Linux

• Referencia de herramientas — Referencia completa de las 144 herramientas con parámetros y rangos

• Edición basada en transcripciones — Guía de flujo de trabajo para podcasts, entrevistas y conferencias (edición basada en etiquetas)

• Contribución — Cómo añadir herramientas y contribuir

• Registro de cambios — Historial de versiones y notas de lanzamiento

Agradecimientos

Gracias a los siguientes por los errores reportados, ideas y comentarios que mejoraron este proyecto:

• @Harsha-Jay-S — diagnosticó el error de effect_change_pitch/effect_change_speed (#15) con pruebas medidas contra Audacity real, identificando la causa raíz exacta.

Licencia

Apache License 2.0 — consulta LICENSE para más detalles.

Creado por Daniel Hodgetts • 𝕏 @daehonz1