earshot MCP
Ears for coding agents: an MCP server and CLI that describe sound in words, review a film's audio and make sounds in code, locally on CPU
- 3,986 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- Installation downloads two models and runs a local Python process
- The llm command uploads audio to the external Gemini service, but only with the flag and your key
- Rendering sounds writes files to disk and loads the CPU
Install
- Works in
Manual install
git clone https://github.com/Leonxlnx/earshot && cd earshot && python -m venv .venv && .venv/bin/python -m pip install torch --index-url https://download.pytorch.org/whl/cpu && .venv/bin/python -m pip install -e ".[mcp,llm,dev]"Then check the install with `.venv/bin/python -m earshot doctor --load`. Python 3.10 or newer and ffmpeg are required.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- Installation downloads two models and runs a local Python process
- The llm command uploads audio to the external Gemini service, but only with the flag and your key
- Rendering sounds writes files to disk and loads the CPU
This is third-party code. Review the repository files before installing.
What it does
earshot turns sound into data an agent can work with. `earshot describe` describes a file in words and measurements, `earshot match` rates how well a sound fits a description, `earshot find` cuts the best moment out of a long recording and `earshot realness` tells a real recording from code-synthesized audio. For a finished film `earshot timeline` builds a second-by-second text transcript of the sound tied to picture cuts, `earshot sheet` draws an annotated image and `earshot critique` checks the film against a scale of professional launch films and returns timestamped fixes. The agent can also make sounds. `earshot forge` writes a sound as a physical-synthesis recipe and improves it by listening to a critic's score. `earshot sfx` serves a sound from a bank of 252 effects and `earshot kit` assembles a whole film's effects. Everything runs locally on CPU as a CLI, a Python API and an MCP server. Two skills ship with it: earshot explains which command answers which question, and real-sound describes a process for scoring videos from licensed recordings.
Who it is for. For makers of videos, games and animation who build video in code and want Claude Code to check and choose sound.
Good fit when
- You need to pick the best match for a description from a folder of downloaded effects
- A long recording needs a clean moment, such as a single key press
- You want to check that a film's sound lines up with picture cuts and does not sink under the music
- Sound must be made in code with no outside recordings, as in films built with Remotion or HyperFrames
- You need to compare two mix versions in words and numbers
Not a fit when
- You need text-to-speech or music generation: earshot rates and synthesizes effects and does not make voices or songs
- You need a quick loudness reading: `earshot measure` or ffmpeg is enough, and no models load for it
- You want sound analysis in the cloud with nothing to install: earshot installs from source and runs on your machine
Example request
Run film.mp4 through earshot critique and show what to fix first in the soundMCP
- Transport
- stdio
- Authentication
- not required
Environment variables
EARSHOT_THREADS- Number of CPU threads, 2 to 3 on a shared machine
GEMINI_API_KEYsecret- Gemini key, needed only for the llm command
Limitations
Python 3.10 or newer and ffmpeg are required. The first use of the models downloads two open models, about 1.1 GB, and after that they are loaded only from the local cache. Each CLI call reloads the models for 20 to 40 seconds. For a series of calls use the MCP server or one Python script. The reference recordings for `earshot forge --refset` are licensed and not in the repository. Your own recordings plug in with `--refs`. The project is young: version 0.4.
How to disable. Run `claude mcp remove earshot` and delete the copied skills from `~/.claude/skills/`. The models sit in the repository's `.cache/hf` folder or in the directory set by `EARSHOT_HOME`.
FAQ
How do I connect earshot to Claude Code?
Install the project in a virtual environment and run `claude mcp add earshot --scope user -e EARSHOT_THREADS=3 -- /path/to/earshot/.venv/bin/python -m earshot mcp` with your own path. The models load on the first call; on a slow machine start Claude Code with `MCP_TIMEOUT=60000`.
Does audio leave my computer?
No, with one exception. The `earshot llm` command uploads audio to Gemini, and only with the `--yes-upload` flag and your own key. Every other command runs locally on CPU.
How does the earshot skill differ from real-sound?
earshot tells the agent which command answers which question and when not to trust it. real-sound describes a full process for scoring a video: sourcing licensed recordings, music edit, mix, mastering, credits and mux.
What does earshot forge do?
It writes a sound as a physical-synthesis recipe, scores candidates with a critic and searches for the best with an evolutionary search. The agent reads the critic's words, rewrites the recipe and runs it again.
How many effects are in the sound bank?
Version 0.4 holds 252 effects, all stored as code and rendered by id in seconds, with no models and no network.
Discussion
No questions or reviews yet.
Related
MCP serversA local sound studio with an MCP server: an agent makes effects, music, songs and speech on open-weight models
A local video studio for your coding agent: describe a video in one sentence, the agent directs, your machine renders with no cloud
Skills, a CLI and an MCP server that let Claude Code or Codex make video from a brief: editing, graphics, voiceover, subtitles
Local speech synthesis for agents: a command and a skill voice text, clone a voice from a recording and render scores to audio, with no cloud
A skill and CLI: the agent writes a script and scenes, while the voice, word timing and MP4 render run on your computer with no API keys
A skill and CLI that let Claude Code or Codex make videos as web pages, with the Studio editor to change the result
README in short
The project opens with the idea that agents can write the code of films but cannot hear the result. Then come a command table, sound synthesis, the effect bank and film kits, installation, MCP setup and quality checks with measurements.