@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

Authentication

Three ways to authenticate, from easiest to most manual:

Method	Setup	Best For
claude.ai Connector	Click "Add" in claude.ai Connectors Directory	claude.ai web/mobile (OAuth automatic)
API Key (stdio)	Set `HEAR_API_KEY` in config	Claude Desktop, Claude Code
OAuth 2.1 (Streamable HTTP)	Connect to `https://api.h-ear.world/mcp`	Claude Code remote, custom MCP clients

Two tools (healthCheck, listClasses) work without any authentication.

claude.ai (easiest — zero config)

Search for "H-ear" in Settings > Connectors on claude.ai. OAuth login is automatic.

Claude Desktop (API key)

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", "HEAR_ENV": "prod" }
    }
  }
}

Windows MSIX users: The config file is at %LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json, NOT at %APPDATA%\Claude\. The "Edit Config" button opens the wrong path.

Claude Code (API key)

Add to .claude/settings.json:

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

Claude Code (OAuth — remote)

claude mcp add --transport http h-ear https://api.h-ear.world/mcp

OAuth discovery is automatic via RFC 9728 Protected Resource Metadata. Run /mcp in Claude Code to authenticate via browser.

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