H Ear 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