# Freesound Mcp Server

> MCP server for audio/sfx search from freesound.org

- **Type:** MCP server
- **Install:** `agentstack add mcp-johnkimdw-freesound-mcp-server`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [johnkimdw](https://agentstack.voostack.com/s/johnkimdw)
- **Installs:** 0
- **Category:** [Content & Media](https://agentstack.voostack.com/c/content-and-media)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [johnkimdw](https://github.com/johnkimdw)
- **Source:** https://github.com/johnkimdw/freesound-mcp-server

## Install

```sh
agentstack add mcp-johnkimdw-freesound-mcp-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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": ""
      }
    }
  }
}
```

### 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": ""
      }
    }
  }
}
```

## 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
```

## 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.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [johnkimdw](https://github.com/johnkimdw)
- **Source:** [johnkimdw/freesound-mcp-server](https://github.com/johnkimdw/freesound-mcp-server)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-johnkimdw-freesound-mcp-server
- Seller: https://agentstack.voostack.com/s/johnkimdw
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.