@h-ear/mcp-server

MCP server for the H-ear World audio classification API. Connect Claude, ChatGPT, Copilot, and other AI agents to 521+ sound classes.

Quick Start

npx @h-ear/mcp-server --key ncm_sk_your_key

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "h-ear": {
      "command": "npx",
      "args": ["-y", "@h-ear/mcp-server"],
      "env": { "HEAR_API_KEY": "ncm_sk_your_key" }
    }
  }
}

Claude Code

Add to .claude/settings.json:

{
  "mcpServers": {
    "h-ear": {
      "command": "npx",
      "args": ["-y", "@h-ear/mcp-server"],
      "env": { "HEAR_API_KEY": "ncm_sk_your_key" }
    }
  }
}

Tools

Tool	Description	Auth
`classifyAudio`	Classify a single audio file or URL (MP3, WAV, FLAC, OGG, M4A). Supports files up to 25 MB with automatic chunking for larger files.	API Key
`classifyBatch`	Batch classify up to 50 audio files or URLs.	API Key
`listClasses`	List 521+ supported audio classes across 3 taxonomies (AudioSet/YAMNet, AudioSet/PANNs, Species).	None
`healthCheck`	API liveness check.	None

Resources

URI	Description
`h-ear://status`	Live API status with health, version, available taxonomies, and class counts.

Prompts

Name	Description
`classify-audio`	Pre-built classification workflow prompt with configurable detail level.

Options

--key <key>        API key (or set HEAR_API_KEY env var)
--env <env>        Environment: dev, staging, prod (default: prod)
--base-url <url>   Override API base URL
--help, -h         Show help

Environment Variables

Variable	Description	Default
`HEAR_API_KEY`	H-ear Enterprise API key	(required for classify tools)
`HEAR_ENV`	Target environment	`prod`
`HEAR_BASE_URL`	Override base URL	Environment default

Large File Support

Files larger than 25 MB are automatically split into 120-second chunks with 30-second overlap using ffmpeg. Results are merged via time-chop deduplication. Requires ffmpeg and ffprobe on PATH.

Small files (<25 MB) and URL mode work without ffmpeg. If ffmpeg is not found and a large file is provided, the server returns a clear error message.

Installing ffmpeg

Platform	Command
macOS	`brew install ffmpeg`
Ubuntu/Debian	`sudo apt-get install ffmpeg`
Windows	`winget install ffmpeg` or `choco install ffmpeg`

Claude Desktop timeout

Claude Desktop has a hardcoded 60-second MCP timeout. Large file chunking + classification can exceed this. Workarounds:

Claude Code: Set MCP_TIMEOUT=300000 (5 min) environment variable
Claude Desktop: Use URL mode (url parameter) instead of filePath for large files -- the API fetches the file server-side with no timeout concern

Supported Formats

MP3, WAV, FLAC, OGG, M4A

Requirements

Node.js >= 18
ffmpeg + ffprobe (optional -- only needed for local files >25 MB)

Get an API Key

Visit h-ear.world to create an account and generate an API key.

License

MIT