Freesound MCP Server

Busca y descubre contenido de audio de Freesound.org para edición de video y creación de contenido.

Documentación

Freesound MCP Server

Un servidor de Model Context Protocol (MCP) que se integra con Freesound.org, permitiendo a los agentes de IA buscar y descubrir contenido de audio para flujos de trabajo de edición de video y creación de contenido.

Características

El Freesound MCP Server permite a los asistentes de IA:

Buscar contenido de audio: Encontrar efectos de sonido, sonidos ambientales y bucles musicales mediante consultas en lenguaje natural
Acceder a metadatos: Obtener información detallada sobre archivos de audio, incluyendo duración, etiquetas, licencias y descripciones
Vista previa del contenido: Acceder a URLs de vista previa para una evaluación inmediata de reproducción de audio
Cumplimiento de licencias: Recuperar información de licencias para garantizar la atribución adecuada y los derechos de uso

Instalación

Requisitos previos

Necesitarás obtener una clave de API de Freesound:

Crea una cuenta en Freesound.org
Solicita una clave de API en https://freesound.org/api/apply/
Una vez aprobada, anota tu clave de API para la configuración

Instalación con Docker (Recomendada)

La forma más sencilla de ejecutar el Freesound MCP Server es usando Docker. No se requiere instalación local de Python.

Configuración

Clona el repositorio:

git clone https://github.com/johnkimdw/freesound-mcp-server.git
cd freesound-mcp-server

Construye la imagen de Docker:

docker build -t freesound-mcp .

Claude Desktop

Añade la siguiente configuración al archivo de configuración de Claude Desktop:

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

{
  "mcpServers": {
    "freesound": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "FREESOUND_API_KEY",
        "freesound-mcp"
      ],
      "env": {
        "FREESOUND_API_KEY": "<YOUR_FREESOUND_API_KEY>"
      }
    }
  }
}

Instalación local

Si prefieres no usar Docker, puedes instalar y ejecutar el servidor localmente usando Python y uv.

Requisitos

Python 3.10+
Gestor de paquetes uv

Configuración

Clona el repositorio:

git clone https://github.com/johnkimdw/freesound-mcp-server.git
cd freesound-mcp-server

Instala las dependencias:

uv sync

Establece tu clave de API:

export FREESOUND_API_KEY=your_api_key_here

Configuración de Claude Desktop

{
  "mcpServers": {
    "freesound": {
      "command": "/path/to/uv",
      "args": [
        "--directory",
        "/path/to/freesound-mcp-server",
        "run",
        "freesound-mcp"
      ],
      "env": {
        "FREESOUND_API_KEY": "<YOUR_FREESOUND_API_KEY>"
      }
    }
  }
}

Uso

Una vez configurado, puedes interactuar con el Freesound MCP Server a través de tu asistente de IA. Aquí tienes algunos ejemplos de consultas:

"Busca efectos de sonido de truenos para una escena de tormenta"
"Busca sonidos ambientales de ciudad de menos de 30 segundos"
"Busca bucles de música de piano con licencia Creative Commons"
"Busca efectos de sonido de perros ladrando"
"Busca audio de fondo de olas del océano"

Herramientas disponibles

search_sounds

Busca archivos de audio en Freesound.org usando consultas en lenguaje natural.

Parámetros:

query (cadena, obligatorio): Términos de búsqueda para contenido de audio
max_results (entero, opcional): Número de resultados a devolver (1-30, predeterminado: 10)

Devuelve:

Metadatos del archivo de audio, incluyendo:
- Nombre del archivo y descripción
- Duración y formato del archivo
- Etiquetas y categorías
- Información de licencia
- URLs de vista previa (alta y baja calidad)
- Información del usuario que subió el archivo
- Enlaces directos a las páginas de Freesound.org

Opciones de transporte

El servidor admite múltiples métodos de transporte para diferentes escenarios de implementación:

Transporte Stdio (Predeterminado)

Se utiliza para la integración local con Claude Desktop y otros clientes MCP:

uv run freesound-mcp
# python -m freesound_mcp.server --transport stdio

Development

Building from Source

# Clone the repository
git clone https://github.com/yourname/freesound-mcp-server.git
cd freesound-mcp-server

# Install dependencies
uv sync

# Run tests
uv run pytest

# Build Docker image
docker build -t freesound-mcp .

Pruebas

Usa el MCP Inspector para depuración detallada:

npx @modelcontextprotocol/inspector uv run freesound-mcp

Licencias y atribución

Este servidor MCP respeta los términos de servicio y las pautas de uso de la API de Freesound.org. Todo el contenido de audio recuperado a través de este servidor:

Se origina en Freesound.org y está sujeto a sus términos de licencia
Requiere la atribución adecuada según lo especificado por las licencias de cada archivo
Debe utilizarse en cumplimiento con Creative Commons y otras licencias aplicables

Importante: Revisa siempre la información de licencia proporcionada con cada archivo de audio para garantizar el cumplimiento de los requisitos de atribución y las restricciones de uso.

Manejo de errores

El servidor incluye un manejo integral de errores para escenarios comunes:

Clave de API no válida: Mensajes de error claros cuando falla la autenticación
Límite de velocidad: Manejo automático de los límites de velocidad de la API con respuestas de error apropiadas
Problemas de red: Manejo de tiempos de espera y gestión de errores de conexión
Consultas no válidas: Validación y saneamiento de entradas

Configuración

Variables de entorno

FREESOUND_API_KEY (obligatorio): Tu clave de API de Freesound.org

Configuración avanzada

Para usuarios avanzados, hay opciones de configuración adicionales disponibles a través de argumentos de línea de comandos:

python -m freesound_mcp.server --help

Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulta el archivo LICENSE para más detalles.

El contenido de audio al que se accede a través de este servidor es proporcionado por Freesound.org y está sujeto a licencias Creative Commons individuales y otras licencias abiertas según lo especificado por los creadores de contenido.