# Freesound MCP Server
A Model Context Protocol (MCP) server that integrates with [Freesound.org](https://freesound.org), enabling AI agents to search and discover audio content for video editing and content creation workflows.
## Features
The Freesound MCP Server enables AI assistants to:
- **Search Audio Content**: Find sound effects, ambient sounds, and music loops using natural language queries
- **Access Metadata**: Get detailed information about audio files including duration, tags, licensing, and descriptions
- **Preview Content**: Access preview URLs for immediate audio playback evaluation
- **License Compliance**: Retrieve licensing information to ensure proper attribution and usage rights
## Installation
### Prerequisites
You will need to obtain a Freesound API key:
1. Create an account at [Freesound.org](https://freesound.org)
2. Apply for an API key at [https://freesound.org/api/apply/](https://freesound.org/api/apply/)
3. Once approved, note your API key for configuration
### Docker Installation (Recommended)
The easiest way to run the Freesound MCP Server is using Docker. No local Python installation required.
#### Setup
1. Clone the repository:
```bash
git clone https://github.com/johnkimdw/freesound-mcp-server.git
cd freesound-mcp-server
```
2. Build docker image:
```bash
docker build -t freesound-mcp .
```
#### Claude Desktop
Add the following configuration to your Claude Desktop config file:
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"freesound": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"FREESOUND_API_KEY",
"freesound-mcp"
],
"env": {
"FREESOUND_API_KEY": "<YOUR_FREESOUND_API_KEY>"
}
}
}
}
```
### Local Installation
If you prefer not to use Docker, you can install and run the server locally using Python and uv.
#### Requirements
- Python 3.10+
- [uv](https://github.com/astral-sh/uv) package manager
#### Setup
1. Clone the repository:
```bash
git clone https://github.com/johnkimdw/freesound-mcp-server.git
cd freesound-mcp-server
```
2. Install dependencies:
```bash
uv sync
```
3. Set your API key:
```bash
export FREESOUND_API_KEY=your_api_key_here
```
#### Claude Desktop Configuration
```json
{
"mcpServers": {
"freesound": {
"command": "/path/to/uv",
"args": [
"--directory",
"/path/to/freesound-mcp-server",
"run",
"freesound-mcp"
],
"env": {
"FREESOUND_API_KEY": "<YOUR_FREESOUND_API_KEY>"
}
}
}
}
```
## Usage
Once configured, you can interact with the Freesound MCP Server through your AI assistant. Here are some example queries:
- "Find thunder sound effects for a storm scene"
- "Search for ambient city sounds under 30 seconds"
- "Look for piano music loops with Creative Commons licensing"
- "Find dog barking sound effects"
- "Search for ocean waves background audio"
## Available Tools
### search_sounds
Search for audio files on Freesound.org using natural language queries.
**Parameters:**
- `query` (string, required): Search terms for audio content
- `max_results` (integer, optional): Number of results to return (1-30, default: 10)
**Returns:**
- Audio file metadata including:
- File name and description
- Duration and file format
- Tags and categories
- License information
- Preview URLs (high and low quality)
- Uploader information
- Direct links to Freesound.org pages
## Transport Options
The server supports multiple transport methods for different deployment scenarios:
### Stdio Transport (Default)
Used for local integration with Claude Desktop and other MCP clients:
```bash
uv run freesound-mcp
# python -m freesound_mcp.server --transport stdio
```
<!--
### HTTP Transport
For web integration or custom deployments:
```bash
python -m freesound_mcp.server --transport http --port 8000
```
### Streamable HTTP Transport
For advanced streaming scenarios:
```bash
python -m freesound_mcp.server --transport streamable-http --port 8000
``` -->
## Development
### Building from Source
```bash
# 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 .
```
### Testing
Use the MCP Inspector for detailed debugging:
```bash
npx @modelcontextprotocol/inspector uv run freesound-mcp
```
## Licensing and Attribution
This MCP server respects Freesound.org's terms of service and API usage guidelines. All audio content retrieved through this server:
- Originates from Freesound.org and is subject to their licensing terms
- Requires proper attribution as specified by individual file licenses
- Should be used in compliance with Creative Commons and other applicable licenses
**Important**: Always review the licensing information provided with each audio file to ensure compliance with attribution requirements and usage restrictions.
## Error Handling
The server includes comprehensive error handling for common scenarios:
- **Invalid API Key**: Clear error messages when authentication fails
- **Rate Limiting**: Automatic handling of API rate limits with appropriate error responses
- **Network Issues**: Timeout handling and connection error management
- **Invalid Queries**: Input validation and sanitization
## Configuration
### Environment Variables
- `FREESOUND_API_KEY` (required): Your Freesound.org API key
### Advanced Configuration
For advanced users, additional configuration options are available through command-line arguments:
```bash
python -m freesound_mcp.server --help
```
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
The audio content accessed through this server is provided by Freesound.org and is subject to individual Creative Commons and other open licenses as specified by content creators.
