@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 + PKCE (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 2.1 + PKCE discovery is automatic via RFC 9728 Protected Resource Metadata. Run /mcp in Claude Code to authenticate via browser — no API key needed.

Tools

14 tools across classification, account, and webhook management:

Tool	Description	Auth
`classifyAudio`	Classify a single audio file or URL (MP3, WAV, FLAC, OGG, M4A). No file size limit — large local files are split automatically into chunks via ffmpeg (requires ffmpeg on PATH); URL mode is fetched server-side with no client upload.	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 — status, version, deployment timestamp.	None
`usage`	API quota: minutes used, calls today, remaining balance.	API Key
`listJobs`	Paginated classification job history with status and filename.	API Key
`getJob`	Detailed job result with all detected sound events and timestamps.	API Key
`createWebhook`	Create enterprise webhook with event/taxonomy/tier filters. Returns signing secret once.	Bearer (enterprise)
`listWebhooks`	List all enterprise webhook registrations.	Bearer (enterprise)
`getWebhook`	Get webhook details including filter config and delivery stats.	Bearer (enterprise)
`updateWebhook`	Update webhook URL, events, status (active/paused), or filters.	Bearer (enterprise)
`deleteWebhook`	Permanently delete a webhook registration.	Bearer (enterprise)
`pingWebhook`	Send a test.ping event to verify connectivity and signing.	Bearer (enterprise)
`listWebhookDeliveries`	Delivery audit trail with response status and timing.	Bearer (enterprise)

Web/Connector note: classifyAudio(filePath) and classifyBatch(filePaths) require local filesystem access — unavailable via the claude.ai Connector (Streamable HTTP). Use url parameters instead, or switch to stdio transport.

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