@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). Supports optional GPS coordinates (`latitude`/`longitude`) for location tagging. No file size limit — large local files are uploaded via byte-slice chunking (no ffmpeg required); URL mode is fetched server-side with no client upload.	API Key
`classifyBatch`	Batch classify up to 50 audio files or URLs. Supports optional GPS (`latitude`/`longitude`) applied to all files.	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 uploaded via byte-slice chunking. Raw 25 MB slices of the original file are uploaded sequentially to the server, which reassembles them via Azure AppendBlob. No ffmpeg required. Original file quality preserved.

No dependencies — no ffmpeg, no temp files, no re-encoding
Memory efficient — one 25 MB buffer at a time
Resumable — per-chunk retry with exponential backoff

Claude Desktop timeout

Claude Desktop has a hardcoded 60-second MCP timeout. Large file uploads 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

GPS / Location

Pass latitude and longitude to classifyAudio or classifyBatch to tag recordings with GPS coordinates. Both must be provided together (decimal degrees: lat -90..90, lng -180..180).

The server applies a priority cascade: file-embedded GPS > client-provided GPS > IP geolocation. Location data is returned in the job result via getJob when available.

Supported Formats

MP3, WAV, FLAC, OGG, M4A

Requirements

Node.js >= 18

Get an API Key

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

License

MIT