MCP 服务器

Freesound MCP

Enables searching and downloading audio samples from Freesound using keywords, filters, and sound IDs. It provides detailed sound metadata including duration, license information, and preview URLs.

README

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

Clone this repository:

git clone <repository-url>
cd freesound-mcp

Install dependencies:

npm install

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
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 兼容的应用程序无缝协作

安装

克隆此仓库：

git clone <repository-url>
cd freesound-mcp

安装依赖：

npm install

设置您的 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"
      }
    }
  }
}