Freesound MCP Server

Pesquise e descubra conteúdo de áudio do

Documentação

Freesound MCP Server

Um servidor Model Context Protocol (MCP) que se integra ao Freesound.org, permitindo que agentes de IA pesquisem e descubram conteúdo de áudio para fluxos de trabalho de edição de vídeo e criação de conteúdo.

Features

O Freesound MCP Server permite que assistentes de IA:

Pesquisar Conteúdo de Áudio: Encontre efeitos sonoros, sons ambientes e loops musicais usando consultas em linguagem natural
Acessar Metadados: Obtenha informações detalhadas sobre arquivos de áudio, incluindo duração, tags, licenciamento e descrições
Pré-visualizar Conteúdo: Acesse URLs de pré-visualização para avaliação imediata de reprodução de áudio
Conformidade de Licença: Recupere informações de licenciamento para garantir atribuição adequada e direitos de uso

Instalação

Pré-requisitos

Você precisará obter uma chave de API do Freesound:

Crie uma conta em Freesound.org
Solicite uma chave de API em https://freesound.org/api/apply/
Após a aprovação, anote sua chave de API para configuração

Instalação via Docker (Recomendado)

A maneira mais fácil de executar o Freesound MCP Server é usando Docker. Não é necessária instalação local de Python.

Configuração

Clone o repositório:

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

Construa a imagem Docker:

docker build -t freesound-mcp .

Claude Desktop

Adicione a seguinte configuração ao arquivo de configuração do 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>"
      }
    }
  }
}

Instalação Local

Se você preferir não usar Docker, pode instalar e executar o servidor localmente usando Python e uv.

Requisitos

Python 3.10+
uv gerenciador de pacotes

Configuração

Clone o repositório:

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

Instale as dependências:

uv sync

Defina sua chave de API:

export FREESOUND_API_KEY=your_api_key_here

Configuração do 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

Após a configuração, você pode interagir com o Freesound MCP Server por meio do seu assistente de IA. Aqui estão alguns exemplos de consultas:

"Encontre efeitos sonoros de trovão para uma cena de tempestade"
"Pesquise sons ambientes de cidade com menos de 30 segundos"
"Procure loops de música de piano com licenciamento Creative Commons"
"Encontre efeitos sonoros de cachorro latindo"
"Pesquise áudio de fundo de ondas do oceano"

Ferramentas Disponíveis

search_sounds

Pesquise arquivos de áudio no Freesound.org usando consultas em linguagem natural.

Parâmetros:

query (string, obrigatório): Termos de pesquisa para conteúdo de áudio
max_results (inteiro, opcional): Número de resultados a retornar (1-30, padrão: 10)

Retorna:

Metadados do arquivo de áudio, incluindo:
- Nome do arquivo e descrição
- Duração e formato do arquivo
- Tags e categorias
- Informações de licença
- URLs de pré-visualização (alta e baixa qualidade)
- Informações do uploader
- Links diretos para páginas do Freesound.org

Opções de Transporte

O servidor suporta vários métodos de transporte para diferentes cenários de implantação:

Transporte Stdio (Padrão)

Usado para integração local com Claude Desktop e outros 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 .

Testes

Use o MCP Inspector para depuração detalhada:

npx @modelcontextprotocol/inspector uv run freesound-mcp

-->

Licenciamento e Atribuição

Este servidor MCP respeita os termos de serviço e as diretrizes de uso da API do Freesound.org. Todo o conteúdo de áudio recuperado por meio deste servidor:

Origina-se do Freesound.org e está sujeito aos seus termos de licenciamento
Requer atribuição adequada conforme especificado pelas licenças individuais dos arquivos
Deve ser usado em conformidade com Creative Commons e outras licenças aplicáveis

Importante: Sempre revise as informações de licenciamento fornecidas com cada arquivo de áudio para garantir conformidade com os requisitos de atribuição e restrições de uso.

Tratamento de Erros

O servidor inclui tratamento abrangente de erros para cenários comuns:

Chave de API Inválida: Mensagens de erro claras quando a autenticação falha
Limitação de Taxa: Tratamento automático dos limites de taxa da API com respostas de erro apropriadas
Problemas de Rede: Tratamento de tempo limite e gerenciamento de erros de conexão
Consultas Inválidas: Validação e sanitização de entrada

Configuração

Variáveis de Ambiente

FREESOUND_API_KEY (obrigatório): Sua chave de API do Freesound.org

Configuração Avançada

Para usuários avançados, opções de configuração adicionais estão disponíveis por meio de argumentos de linha de comando:

python -m freesound_mcp.server --help

Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para obter detalhes.

O conteúdo de áudio acessado por meio deste servidor é fornecido pelo Freesound.org e está sujeito a licenças individuais Creative Commons e outras licenças abertas, conforme especificado pelos criadores de conteúdo.