Provides optional integration with Google Gemini's audio understanding API to analyze uploaded guitar clips and return cautious listening descriptions covering gain level, brightness, low end, mids character, pick attack, compression feel, effects, playing notes, timestamped evidence, uncertainties, and confidence. It also supports A/B comparison of two uploaded clips via Gemini to identify differences and suggested adjustments.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@tone-listener-mcp Compare candidate.wav to reference.wav and suggest EQ and gain changes."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server that lets AI agents listen to guitar tone recordings and compare a candidate tone against a reference. Use it to guide relative gain, EQ and effects adjustments in software such as Soundshed Guitar, not to guess exact equipment.
Local NumPy/SciPy measurements handle levels, spectrum, dynamics and stereo. Optional Gemini audio understanding adds cautious descriptions of what is audible. Without an API key, analysis and comparison still return local measurements.
Requires Python 3.11 or newer. Run from this repository:
python -m venv .venv
.venv/bin/pip install -e '.[dev]'Runtime dependencies are MCP, NumPy, SciPy, SoundFile and google-genai, plus Pydantic for response validation and HTTPX for typed provider-error handling. No librosa or ffmpeg is required. SoundFile wheels bundle libsndfile, including MP3 support. WAV, FLAC, OGG and MP3 are supported when the installed decoder can read them. Convert M4A/AAC to WAV with your DAW or another converter first.
Related MCP server: beatlyzer-mcp
Variable | Default | Purpose |
| Unset | Enable Gemini uploads and listening; omit for local-only operation |
|
| Audio-capable Gemini model available to your account |
|
| Maximum selected duration; positive finite seconds |
.env.example is a reference, not automatically loaded. Export variables in
your shell or set them in your MCP client's environment configuration. Never
commit a real key. Model availability, API access and billing depend on your
Google account. The default follows the current Gemini audio documentation;
the backend uses the SDK Files upload and models.generate_content APIs.
export GEMINI_API_KEY="your-key"
.venv/bin/tone-listener-mcpThe server speaks MCP over stdio, not an interactive terminal interface.
Generic mcpServers configuration (replace the absolute path):
{
"mcpServers": {
"tone-listener": {
"command": "/absolute/path/to/tone-listener-mcp/.venv/bin/tone-listener-mcp",
"env": {
"GEMINI_API_KEY": "your-key"
}
}
}
}VS Code .vscode/mcp.json uses servers and supports a secret input:
{
"inputs": [
{
"type": "promptString",
"id": "gemini-key",
"description": "Gemini API key",
"password": true
}
],
"servers": {
"tone-listener": {
"type": "stdio",
"command": "/absolute/path/to/tone-listener-mcp/.venv/bin/tone-listener-mcp",
"env": {
"GEMINI_API_KEY": "${input:gemini-key}"
}
}
}
}For offline use, omit GEMINI_API_KEY and the VS Code secret input. Paths to audio
are resolved on the machine running this server, not necessarily the client machine.
All tools return structured JSON as well as MCP-compatible content. Invalid files
or intervals return an MCP tool error. Times are seconds; start defaults to zero,
end is exclusive and defaults to EOF. An endpoint past EOF is clamped to EOF.
~ is expanded, and original channels/sample rate are retained for local metrics.
Only mono/stereo audio up to 192 kHz is accepted. Selected float32 decoded audio is
limited to 128 MiB in addition to the duration cap; shorten clips when either
limit is exceeded.
Tool | Arguments | Result |
| None | Server name and version |
|
| Local clip metadata, level, spectrum and stereo metrics; never uploads |
|
| Local |
|
| Reference A vs candidate B, RMS matching, deltas, EQ directions and optional A/B listening |
Example requests to an agent's MCP tool interface:
{"path": "/recordings/reference.wav", "start": 12, "end": 20}{
"path_a": "/recordings/reference.wav",
"path_b": "/recordings/candidate.wav",
"focus": "How should I change B's brightness and drive to approach A?"
}For a 0.5-peak, 1 kHz synthetic sine, selected fields look like this (values rounded; this is an excerpt, not the complete response):
{
"level": {
"peak_dbfs": -6.02,
"rms_dbfs": -9.03,
"crest_factor_db": 3.01,
"short_term_rms_range_db": 0.0,
"silent_window_fraction": 0.0
},
"spectrum": {
"centroid_hz": 1000.0,
"rolloff_85_hz": 1007.81,
"bands": {
"800_2000": {"available": true, "relative_db": 0.0}
}
},
"stereo": null
}Levels include 50 ms short-term RMS power percentiles (p10, p50, p90) and range
as dynamics proxies. These are not LUFS or a perceptual loudness measurement.
Spectrum uses Welch's method with a Hann window and up to 4096 frames, averaging
channel powers so antiphase stereo does not disappear. Frequency resolution and
Nyquist are reported. Band IDs cover <80, 80-250, 250-800, 800-2000,
2000-5000, 5000-8000 and >8000 Hz. relative_db is band power relative
to total spectral power, not an absolute EQ control value.
Stereo reports L/R correlation and side/mid energy ratio dB, with separate mid
and side RMS levels. null means undefined or unavailable, including silence,
mono stereo metrics, zero side/mid energy, or bands above Nyquist. A short-term
range containing a zero-energy window is undefined; inspect
silent_window_fraction as well. No NaN or Infinity is returned.
analyze_audio returns a listening object with summary, gain_level,
brightness, low_end, mids_character, pick_attack, compression_feel,
effects (reverb/delay/modulation presence, amount and notes), playing_notes,
timestamped evidence, uncertainties and confidence.
Gain categories include clean, edge-of-breakup, crunch, overdrive, distortion,
high-gain and uncertain. Evidence timestamps are relative to the selected clip.
No key gives an explicit local-only response:
{
"model": "gemini-3.8-flash",
"listening": null,
"listening_unavailable": "GEMINI_API_KEY is not set; local metrics only",
"cleanup_warnings": [],
"upload_gain_db": 0.0
}This excerpt omits the returned local metrics. Provider errors and invalid
model responses similarly preserve metrics, with a sanitized failure reason.
Confidence is model self-assessment, not calibrated accuracy. Live listening
quality requires evaluation against recordings with known changes.
B is RMS-matched to A before spectral comparison and listening. The response
retains original metrics_a/metrics_b and reports matched_metrics_b,
loudness_match, deltas_b_minus_a and eq_direction_hints. Linear gain alone
should not produce a tonal difference:
{
"loudness_match": {
"applied": true,
"gain_db_applied_to_b": 6.0206,
"reason": null
},
"deltas_b_minus_a": {
"relative_band_db": {"800_2000": 0.0},
"centroid_hz": 0.0,
"rolloff_85_hz": 0.0,
"crest_factor_db": 0.0,
"stereo": null
}
}This excerpt describes B at half A's amplitude. Deltas use B minus A; positive band deltas mean relatively more energy in B. Direction hints suggest cutting or boosting B toward A, not exact gain/EQ knobs. Silence makes RMS matching undefined and is explicitly reported. Stereo deltas require two stereo clips. Gemini compares both uploads in one request and returns differences, which clip is brighter/more saturated/more compressed/more ambient, suggested adjustments and uncertainties.
With a key configured, analyze_audio uploads the selected clip to Google,
and compare_audio uploads both selected clips. Only use recordings you have
permission to share. audio_metrics is always local. Temporary WAVs are deleted
on exit; uploaded files are deleted after the request, including most failure
paths. Cleanup failures are returned in cleanup_warnings. Remote handling and
retention are governed by Google's terms; deletion is not a zero-retention guarantee.
Local paths are included in local result metadata but not intentionally sent in
provider prompts. A user-supplied question/focus is sent to Google.
Uploads are resampled to 16 kHz mono (sample rate, not 16 kbps bitrate).
Stereo and fine high-frequency detail must come from local metrics, not listening
claims. Severe stereo downmix cancellation (more than 40 dB power loss) disables
listening with an explicit reason; provide a mono guitar stem instead.
If loudness matching exceeds full scale, the same attenuation is applied to both
uploads and reported as upload_gain_db; original local measurements are unchanged.
Full mixes can confuse cymbals with guitar fizz, doubling with delay and other instruments with guitar ambience/compression. Isolate the guitar where possible. The tool cannot identify exact amps, pedals, cabinets or knob settings. Spectral differences may reflect notes, pickup position, playing or arrangement rather than EQ. Gemini's descriptions may be wrong; use evidence and listening checks.
Use the same DI and phrase for A/B, avoid clipping, compare at matched loudness and choose short, focused clips. Record dry and processed versions when possible; start/end should cover equivalent musical material.
.venv/bin/ruff check .
.venv/bin/pytest -q
.venv/bin/python scripts/make_validation_set.py --output /tmp/tone-validationSee controlled validation for known gain, soft clipping, EQ and simple reverb variants. Tests are synthetic/offline with mocked Gemini; the stdio integration test spawns the real server and exercises all four tools. GitHub Actions runs lint and tests on Python 3.11 and 3.12 on push or manual dispatch. Live Gemini checks are opt-in, require a key and incur API usage.
MIT. No reference recordings or copyrighted song audio are included.
Measure a clip and optionally upload it to Gemini for guitar listening.
| Name | Required | Description | Default |
|---|---|---|---|
| end | No | ||
| path | Yes | ||
| start | No | ||
| question | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are supplied, so the description carries the full burden. It does disclose something valuable that the schema cannot: audio may be sent to an external Gemini service, which matters for privacy and latency. It omits what triggers that upload, whether it costs quota, and what happens on failure, so the disclosure is partial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
It is a single front-loaded sentence with no padding, which is structurally clean. But the brevity here comes from under-specification rather than economy, so it does not earn a high conciseness score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Placeholder.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% across four parameters, so the description must compensate and largely fails. 'Optionally upload' loosely maps to the 'question' parameter, but path, start, and end (presumably a time window in seconds) get no meaning at all, including units or clipping behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The verb 'measure' plus 'a clip' gives a rough sense of the operation, and 'upload it to Gemini for guitar listening' hints at an optional AI-analysis path. However, 'measure' is unspecified (loudness? tempo? pitch?) and nothing distinguishes it from the sibling audio_metrics, which sounds like it does the same measurement work.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Optionally' implies two modes but never states the condition that selects the Gemini path. There is no guidance on when to use this instead of audio_metrics or compare_audio, so the agent must guess between three audio tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Measure local audio levels, spectrum and stereo. Times are seconds; end is exclusive.
| Name | Required | Description | Default |
|---|---|---|---|
| end | No | ||
| path | Yes | ||
| start | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the measurement type and time semantics but does not confirm read-only behavior, describe error cases, performance characteristics, or what processing is performed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short, front-loaded sentences with no wasted wording. The time-semantics note is immediately adjacent to the purpose statement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be explained. However, given no annotations, 0% schema description coverage, and sibling tools that perform related audio analysis, the description is only minimally complete for correct tool selection and parameter use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for three parameters. It usefully clarifies that times are in seconds and that the end time is exclusive, but it does not explain the meaning or constraints of the path parameter or the default behavior when start is omitted.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb and resource: measure local audio levels, spectrum, and stereo. It is understandable without opening the schema, but it does not distinguish this tool from the sibling analyze_audio or compare_audio.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance on when to use this tool versus analyze_audio or compare_audio. The word 'local' hints at a scope, but the description leaves the agent to infer when this measurement tool is the right choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compare B to reference A with RMS matching and optional Gemini A/B listening.
| Name | Required | Description | Default |
|---|---|---|---|
| end_a | No | ||
| end_b | No | ||
| focus | No | ||
| path_a | Yes | ||
| path_b | Yes | ||
| start_a | No | ||
| start_b | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It doesn't say whether RMS matching alters files on disk, whether the comparison is symmetric, whether the Gemini step incurs cost or extra latency, or what happens when durations differ. The one useful disclosure — that Gemini A/B listening is optional — is the only behavioral context given.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The single sentence is front-loaded and free of waste, but its brevity comes at the cost of under-specification rather than genuine conciseness. It is efficient but leaves too much unsaid for a 7-parameter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values needn't be described. However, for a 7-parameter tool with zero annotation and zero schema description coverage, the description should at minimum explain the time-window parameters and the focus argument, and it does neither.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% across 7 parameters, so the description must compensate and largely doesn't. It clarifies that path_a is the reference and path_b the comparison target, but start_a/start_b/end_a/end_b and focus are left completely unexplained — an agent cannot infer whether offsets are seconds or samples, or whether they must be aligned between A and B.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resources: compare audio B against reference A, with RMS level matching and an optional Gemini A/B listening step. This distinguishes it from audio_metrics and analyze_audio, which measure rather than compare. Sibling differentiation is implicit rather than stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit when-to-use guidance and no mention of when to prefer analyze_audio or audio_metrics instead. The only hint is that the Gemini listening step is optional, which implies a cheap path but doesn't say when to enable it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return basic information about this server.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are supplied, so the description carries the full burden. "Return" implies a non-mutating read, but the description does not explicitly confirm the absence of side effects, permission requirements, or rate limits. For such a lightweight introspection call this is mild, but the description still adds little behavioral context beyond the verb.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with no redundant wording or filler. Every word contributes to identifying the action and target.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (zero parameters) and an output schema exists, so the description need not enumerate return values. The description is adequate for correct invocation, though it could say what categories of server facts are returned to help an agent judge relevance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there are no parameter semantics to document and the baseline of 4 applies. The description does not need to compensate for any schema gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a clear verb ("Return") and resource ("basic information about this server"), so an agent can immediately identify it as a server-introspection call. It is distinct from the audio-focused siblings (audio_metrics, analyze_audio, compare_audio) with no overlap in purpose. The only weakness is that "basic information" is left undefined, so the exact content scope is not stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to call this tool, no prerequisites, and no mention of alternatives or related tools. The description offers no exclusions or conditions under which this tool should be preferred or avoided. The purpose is only inferable from the name itself.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0analyze_audioaudio_metricscompare_audioserver_infoScored across 4 tools
audio_metrics and analyze_audio both measure audio levels/spectrum and differ mainly by an optional Gemini upload step, which makes misselection likely. compare_audio and server_info are clearly distinct, so overlap is limited to one ambiguous pair.
Names are readable but follow mixed conventions: two noun-style names (server_info, audio_metrics) and two verb_noun names (analyze_audio, compare_audio). No camelCase chaos, but there is no single predictable pattern for an agent to rely on.
Four tools is a tight, focused surface for an audio-analysis server, and each tool maps to a plausible workflow. server_info is arguably filler, keeping it from a 5.
The surface covers measurement, single-clip analysis, and A/B comparison, but there is no tool for recording, streaming/live monitoring, or device/input selection despite the 'listener' framing. Agents would hit a dead end on any real-time or capture workflow.
AI mixing and mastering: analyze your mixes, run DSP autofix, render stems, and master tracks.
Audio for your agent: transcribe, speak, translate, summarise, plus sound effects and music.
Audio mastering for AI agents: LUFS/True Peak targets, Suno/Udio AI-fingerprint removal.
AI music production assistant — audio profiling, AI mixing sessions, and service inquiries.