@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