Freesound-MCP

A Model Context Protocol (MCP) server that enables AI applications to search and download audio resources from the Freesound platform via natural language commands.

Overview

Freesound-MCP is designed to simplify the integration of copyright-free sound resources into AI tools. It follows the Model Context Protocol standard and communicates with host applications via stdin/stdout. The server provides two main capabilities:

• 🔍 Search Sounds: Search for sounds by keywords with optional filters for maximum duration and license type
• ⬇️ Download Sounds: Download audio files by sound ID from Freesound
• 🎵 Metadata Support: Retrieve detailed information about sounds, including duration, license, and preview links

Features

• Lightweight MCP server built with Node.js
• Standard input/output communication mechanism compliant with MCP protocol
• Secure API key management through environment variables
• No database required - simple, stateless design

Security Considerations

• Keep your FREESOUND_API_KEY secret and never expose it in client-side code
• Input parameters are validated to prevent malicious IDs from being passed to the API
• The server follows MCP security best practices for communication

Prerequisites

• Node.js (supports CommonJS modules)
• npm or yarn package manager
• A Freesound API key (get one at Freesound API page)

Installation

1. Clone the repository:

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

2. Install dependencies:

npm install

3. Build the project:

npm run build

Setup

1. Get your Freesound API key from Freesound API page

2. Set your API key as an environment variable:

export FREESOUND_API_KEY=your_freesound_api_key_here

Configuration in Claude Desktop

To configure this MCP server in Claude Desktop:

1. Open Claude Desktop preferences
2. Navigate to "Beta Features" → "Model Context Protocol (MCP) Tools"
3. Click "Configure" to manage MCP servers
4. Add a new server configuration with these details:
   • Name: "Freesound MCP"
   • Command: node
   • Arguments: /path/to/freesound-mcp/dist/index.js (after running npm run build)
   • Environment Variables: Ensure FREESOUND_API_KEY is available to the process
5. Save the configuration and restart Claude

After restarting Claude, you'll be able to use the Freesound tools in your conversations.

Usage

Once configured in Claude, you can use natural language commands such as:

• "Find me a rainforest ambient sound under 30 seconds"
• "Download sound #123456 as high quality"

Available Tools

1. Freesound Search (freesound_search)

Search for sounds on Freesound by providing keywords and optional filters.

Parameters:

• query (required): Search keywords
• maxDuration (optional): Maximum duration of sounds in seconds
• license (optional): License type of sounds to search for

Returns:

• Array of sound objects containing:
  • id: Sound ID
  • name: Sound name
  • duration: Sound duration in seconds
  • license: Sound license
  • preview: Sound preview URL

2. Freesound Download (freesound_download)

Download a sound from Freesound by sound ID.

Parameters:

• soundId (required): ID of the sound to download
• quality (optional): Audio quality ('hq' for high quality or 'lq' for low quality), defaults to 'lq'
• downloadDir (optional): Custom download directory, defaults to ~/.freesound-mcp/downloads

Returns:

• filePath: Path where the file was downloaded

License

This project is licensed under the MIT License - see the LICENSE file for details.