H-ear MCP Server
AI-powered sound classification for Claude. Identify sounds, detect noise events, and classify audio across 7,000+ sound classes — from urban noise to bird species.
H-ear connects Claude to the H-ear World audio classification API via the Model Context Protocol.
Quick Start
npx @h-ear/mcp-server --key YOUR_API_KEY
That's it. Claude now has 14 tools (classification, account, webhooks), a live status resource, and a guided classification prompt.
Tools
| Tool | Auth | Description |
|---|---|---|
classifyAudio |
Key | Classify audio from a file or URL. Async submit + poll. Large files auto-chunked. |
classifyBatch |
Key | Batch classify up to 50 files at once. |
listClasses |
None | Browse 521+ sound classes across 3 taxonomies (7,000+ including species). |
healthCheck |
None | API liveness check — status, version, deployment timestamp. |
usage |
Key | API quota: minutes used, calls today, remaining balance. |
listJobs |
Key | Recent classification job history with pagination. |
getJob |
Key | Detailed job result with all detected sound events. |
createWebhook |
Bearer | Create enterprise webhook with event/taxonomy/tier filters. Returns signing secret once. |
listWebhooks |
Bearer | List all enterprise webhook registrations. |
getWebhook |
Bearer | Get webhook details including filter config and delivery stats. |
updateWebhook |
Bearer | Update webhook URL, events, status (active/paused), or filters. |
deleteWebhook |
Bearer | Permanently delete a webhook registration. |
pingWebhook |
Bearer | Send a test.ping event to verify connectivity and signing. |
listWebhookDeliveries |
Bearer | Delivery audit trail with response status and timing. |
Plus:
- Resource
h-ear://status— live API status with taxonomies and class counts - Prompt
classify-audio— guided workflow with configurable detail level
Supported Audio
| Formats | Max Size | Max Duration |
|---|---|---|
| MP3, WAV, FLAC, OGG, M4A | 25 MB (auto-chunked above) | 10 minutes |
Files over 25 MB are automatically split into overlapping chunks using ffmpeg, classified in parallel, then merged with deduplication.
Taxonomies
| Taxonomy | Classes | Use Case |
|---|---|---|
audioset-yamnet-521 |
521 | General sound classification (default) |
audioset-panns-527 |
527 | Extended general classification |
species |
6,522 | Bird species identification |
Authentication
Get an API key from h-ear.world (Enterprise plan). Pass it via:
- Environment variable:
HEAR_API_KEY - CLI flag:
--key YOUR_KEY - OAuth 2.1 + PKCE (automatic via claude.ai Connectors Directory — handled by your MCP client)
Two tools (healthCheck, listClasses) work without authentication.
Transport
| Transport | Endpoint |
|---|---|
| stdio (npm) | npx @h-ear/mcp-server --key YOUR_KEY |
| Streamable HTTP | https://api.h-ear.world/mcp |
Documentation
- Tool Reference — all 7 tools with schemas and parameters
- Examples — real-world use cases with prompts
- Authentication — API keys, OAuth, Enterprise tiers
- Configuration — Claude Desktop, Claude Code, claude.ai setup
- Troubleshooting — common issues and solutions
Links
- npm: @h-ear/mcp-server
- npm: @h-ear/core
- H-ear World
- OpenClaw Skill (WhatsApp, Telegram, Slack, Discord, Teams)
License
MIT
