Freesound MCP | Freesound MCP

English | 中文

---

English

A Model Context Protocol (MCP) server that provides tools to search and download sounds from Freesound.

Features

• 🔍 Search Sounds: Search for sounds using keywords with optional filters
• ⬇️ Download Sounds: Download sounds by their ID
• 🎵 Metadata Support: Get detailed information about sounds including duration, license, and preview URLs
• 🔧 Easy Integration: Works seamlessly with MCP-compatible applications

Installation

1. Clone this repository:

git clone <repository-url>
cd freesound-mcp

2. Install dependencies:

npm install

3. Set up your Freesound API key:

   • Create a .env file in the project root
   • Add your API key: FREESOUND_API_KEY=your_api_key_here
   • Get your API key from Freesound API

4. Test the API functionality:

node example.js

Usage

Available Tools

freesound.search

Search sounds from Freesound.

Parameters:

• query (required): Search keywords
• maxDuration (optional): Maximum duration in seconds
• license (optional): License filter

Example:

{
  "name": "freesound.search",
  "arguments": {
    "query": "rain",
    "maxDuration": 30,
    "license": "Creative Commons 0"
  }
}

freesound.download

Download a sound preview from Freesound by sound ID.

Note: This downloads the MP3 preview (128 kbps). For original high-quality audio files, OAuth2 authentication is required.

Parameters:

• soundId (required): The ID of the sound to download

Example:

{
  "name": "freesound.download",
  "arguments": {
    "soundId": 123456
  }
}

Running the Server

node index.js

The server will start and listen for MCP requests via stdio.

Configuration

Environment Variables

The server requires the following environment variable:

• FREESOUND_API_KEY: Your Freesound API token

MCP Client Configuration

To use this MCP server, add the following configuration to your MCP client's configuration file:

{
  "mcpServers": {
    "freesound": {
      "command": "node",
      "args": ["./freesound-mcp/index.js"],
      "env": {
        "FREESOUND_API_KEY": "your_api_key_here"
      }
    }
  }
}

Replace your_api_key_here with your actual Freesound API key. You can get your API key from Freesound API.

Make sure to adjust the path ./freesound-mcp/index.js if you installed the server in a different location.

Dependencies

• @modelcontextprotocol/sdk: MCP SDK for building servers
• node-fetch: HTTP client for API requests
• dotenv: Environment variable management

License

ISC

---

中文

一个模型上下文协议 (MCP) 服务器，提供从 Freesound 搜索和下载声音的工具。

功能特性

• 🔍 搜索声音: 使用关键词搜索声音，支持可选过滤器
• ⬇️ 下载声音: 通过 ID 下载声音
• 🎵 元数据支持: 获取声音的详细信息，包括时长、许可证和预览 URL
• 🔧 易于集成: 与 MCP 兼容的应用程序无缝协作

安装

1. 克隆此仓库：

git clone <repository-url>
cd freesound-mcp

2. 安装依赖：

npm install

3. 设置您的 Freesound API 密钥：
   • 在项目根目录中创建 .env 文件
   • 添加您的 API 密钥：FREESOUND_API_KEY=your_api_key_here
   • 从 Freesound API 获取您的 API 密钥

使用方法

可用工具

freesound.search

从 Freesound 搜索声音。

参数：

• query (必需): 搜索关键词
• maxDuration (可选): 最大时长（秒）
• license (可选): 许可证过滤器

示例：

{
  "name": "freesound.search",
  "arguments": {
    "query": "雨声",
    "maxDuration": 30,
    "license": "Creative Commons 0"
  }
}

freesound.download

通过声音 ID 从 Freesound 下载声音。

参数：

• soundId (必需): 要下载的声音 ID

示例：

{
  "name": "freesound.download",
  "arguments": {
    "soundId": 123456
  }
}

运行服务器

node index.js

服务器将启动并通过 stdio 监听 MCP 请求。

配置

环境变量

服务器需要以下环境变量：

• FREESOUND_API_KEY: 您的 Freesound API 令牌

MCP 客户端配置

要使用此 MCP 服务器，请将以下配置添加到您的 MCP 客户端配置文件中：

{
  "mcpServers": {
    "freesound": {
      "command": "node",
      "args": ["./freesound-mcp/index.js"],
      "env": {
        "FREESOUND_API_KEY": "你的key"
      }
    }
  }
}

请将 你的key 替换为您实际的 Freesound API 密钥。您可以从 Freesound API 获取 API 密钥。

如果您将服务器安装在不同的位置，请确保调整路径 ./freesound-mcp/index.js。

依赖项

• @modelcontextprotocol/sdk: 用于构建服务器的 MCP SDK
• node-fetch: 用于 API 请求的 HTTP 客户端
• dotenv: 环境变量管理