cosmic-ears-mcp

# COSMIC EARS MCP

**Give your AI ears to the universe.**

Explore genuine radio observations, listen to available recordings, and investigate signals using Claude, Codex, and other MCP-compatible assistants.

[![CI](https://github.com/levanmamulashvili911-byte/cosmic-ears-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/levanmamulashvili911-byte/cosmic-ears-mcp/actions/workflows/ci.yml) ![Python 3.11+](https://img.shields.io/badge/Python-3.11%2B-blue) [![Code license: MIT](https://img.shields.io/badge/code-MIT-teal)](LICENSE)

[Live showcase](https://levanmamulashvili911-byte.github.io/cosmic-ears-mcp/) · [Official MCP Registry](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.levanmamulashvili911-byte%2Fcosmic-ears-mcp/versions/latest) · [Verified launch status](docs/launch/LAUNCH_STATUS.md)

![Real SatNOGS audio/baseband spectrogram, observation 15191199](docs/launch/assets/real-spectrogram.png)

*Actual processed SatNOGS observation [15191199](https://network.satnogs.org/observations/15191199/), 2026-10-12 20:55 UTC. PE0SAT / PE0SAT-12; SatNOGS / Libre Space Foundation. CC BY-SA 4.0. First 15 s, resampled to 16 kHz, mono PCM16, STFT. Human-made satellite target; not natural planetary emission. [Manifest](docs/launch/assets/real-manifest.json).*

Cosmic Ears is a small Python server that gives an AI assistant tools for finding observations, playing permitted recordings, measuring audio, and drawing spectrograms. **MCP** (Model Context Protocol) is the connection between the assistant and those tools. Install this server in Claude Desktop, Claude Code, or Codex to investigate recordings conversationally; the scientific calculations run on your computer, and the host supplies the conversation. The server itself never calls an LLM.

## Quick start — no clone required

Install [uv](https://docs.astral.sh/uv/getting-started/installation/) first. The same command works in Terminal on macOS/Linux and PowerShell on Windows:

```sh
uvx --from https://github.com/levanmamulashvili911-byte/cosmic-ears-mcp/releases/download/v0.2.0/cosmic_ears_mcp-0.2.0-py3-none-any.whl cosmic-ears-mcp self-test
```

This runs a **real offline MCP handshake**, lists all 11 tools, returns audio/image blocks and checks the synthetic 440 Hz tone. The first installation requires internet; the scientific demo then runs offline. The package is distributed through GitHub Releases; **PyPI publication is pending**.

Replace `self-test` with `explore` for a real SatNOGS recording, or `--offline demo` for the labeled synthetic example. Both print artifact paths. Start listening at low volume.

## Connect Claude or Codex

**Codex CLI / IDE:**

```sh
codex mcp add cosmic-ears -- uvx --from https://github.com/levanmamulashvili911-byte/cosmic-ears-mcp/releases/download/v0.2.0/cosmic_ears_mcp-0.2.0-py3-none-any.whl cosmic-ears-mcp serve
```

**Claude Code:**

```sh
claude mcp add --transport stdio --scope user cosmic-ears -- uvx --from https://github.com/levanmamulashvili911-byte/cosmic-ears-mcp/releases/download/v0.2.0/cosmic_ears_mcp-0.2.0-py3-none-any.whl cosmic-ears-mcp serve
```

**Claude Desktop:** use the generated configuration or the MCPB 0.4 UV extension in the release. The extension requires a host supporting the UV runtime; manual stdio setup remains available. [Complete installation guide](docs/installation.md).

Try these prompts:

- “Find a genuine satellite radio recording, play an excerpt, generate its spectrogram, and explain the signal.”
- “Run the offline synthetic demo and explain the tone, sweep, dual tone and noise.”
- “Give me the observation source, observer, station, license and limits of these measurements.”

Codex tool calls, spectrogram display and WAV playback were verified with the real client and user confirmation. Codex omits raw audio from model input, so explanations must use measurements rather than claim the model listened. [Client compatibility](docs/client-compatibility.md). Other hosts may need the returned local file links; Claude GUI testing is deferred.

## Watch the 36-second demonstration

[Horizontal video](https://github.com/levanmamulashvili911-byte/cosmic-ears-mcp/releases/download/v0.2.0/cosmic-ears-horizontal.mp4) · [Vertical video](https://github.com/levanmamulashvili911-byte/cosmic-ears-mcp/releases/download/v0.2.0/cosmic-ears-vertical.mp4) · [Reproduce it](docs/launch/video.md)

An **edited replay of actual stdio MCP output**, not a fabricated Claude/Codex screen. The recording and plot are real; the offline education segment is prominently synthetic. [Attribution and transformations](docs/launch/assets/LICENSES.md).

## Two real-world journeys

**“Let me hear Jupiter.”**

1. Call `cosmic_ears_list_featured` with `category="jupiter"`.
2. Open the credited [Radio JOVE Jupiter examples](https://radiojove.gsfc.nasa.gov/library/multimedia/audio/ufsamples.mp3), courtesy University of Florida Astronomy, from the [original source page](https://radiojove.gsfc.nasa.gov/library/multimedia/).
3. The clip is verified and reachable, but its page provides no explicit reuse license for this contributed recording. The server returns the listening link and provenance; it does **not** automatically download or redistribute it. The offline demo remains separately labeled synthetic.

**“Find a recent satellite recording and analyze it.”**

The quickest route is `cosmic_ears_explore(duration_seconds=15)`: one bounded call returns the recording, plot, measurements and credits. The original granular workflow remains available:

1. Call `cosmic_ears_search_satnogs(audio_only=True, limit=3)`.
2. Use a returned ID with `cosmic_ears_get_audio(provider="satnogs", observation_id="…", max_duration_seconds=30)`.
3. Pass the returned `safe_id` to `cosmic_ears_analyze_audio` and `cosmic_ears_make_spectrogram`.

SatNOGS availability changes. Some observations have no audio; links can expire or exceed the size limit. Those results remain metadata or source links. No fake recording is substituted. Search scans at most three pages and does not claim to search the entire archive.

## Tools you get

| Tool suffix (all begin `cosmic_ears_`) | What it does |
| --- | --- |
| `explore` | One call: find real audio, play an excerpt, plot, measure and preserve credits |
| `list_featured` | Curated Jupiter, RFI, archive and synthetic references |
| `search_satnogs` | Real public observation metadata, bounded search, optional audio filter |
| `get_observation` | Source, observer, station, dates, RF frequency if supplied, media availability |
| `get_audio` | At most 90 seconds of permitted audio as mono 16 kHz PCM WAV |
| `analyze_audio` | Peak/RMS, dominant frequency, spectral centroid, rough spectral floor |
| `make_spectrogram` | Actual Hann-window STFT PNG with seconds and audio/baseband Hz |
| `compare_audio` | Digital contrasts with receiver and processing cautions |
| `export_report` | Markdown evidence report to a directory approved at startup |
| `demo` | Fully offline, deterministic, prominently synthetic audio and plot |
| `status` | Dependencies and limits; optional bounded source checks |

Reports require `--report-dir PATH` or `COSMIC_EARS_REPORT_DIR` at startup. Local audio outside managed artifacts must be selected explicitly with `--allow-file PATH`. Tools cannot fetch arbitrary URLs or choose arbitrary filesystem locations.

## What are we hearing?

**Vacuum does not transmit ordinary sound.** A radio receiver converts electromagnetic signals into electrical/audio signals that can be played through a speaker. Radio JOVE studies natural emissions including Jupiter and the Sun. SatNOGS recordings generally contain transmissions from **human-made satellites**. The demo contains ordinary generated test signals.

A spectrogram of demodulated audio is **not automatically a calibrated RF spectrogram**. Its vertical axis is audio/baseband Hz. Digital loudness is not astronomical flux, and an unusual feature may be radio-frequency interference (RFI), receiver behavior, compression, or modulation. There is no alien detector, alien probability, guaranteed 24/7 stream, live telescope control, or astrophysical classifier here. Read [science and limitations](docs/science-and-limitations.md).

## Provenance and licenses

Original source code and the synthetic demonstration are **MIT licensed**. This does not relicense third-party data, recordings or images.

- **SatNOGS:** API data are [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/). Preserve the source link, observer/station credit, Libre Space Foundation / SatNOGS credit, and license; indicate excerpting/resampling and apply share-alike to distributed adaptations as required. Returned artifacts retain this provenance in JSON, PNG metadata and reports.
- **Radio JOVE:** acknowledge observers/contributors and the Radio JOVE Project. The archive's attribution/training policy is distinct from licensing for contributed multimedia; unknown rights remain unknown. Only source links are bundled.
- No third-party recordings are committed to this repository. The tiny SatNOGS test fixture is an attributed selection of actual API fields; see [its credits](tests/fixtures/README.md).

The [data-source matrix](docs/data-sources.md) records the verified contracts, fields, links, limitations, and licensing decisions.

## Ten things to ask

1. “Run the Cosmic Ears offline demo.”
2. “Let me hear Jupiter. Give me the original source and credits.”
3. “Show me a recent satellite observation with audio.”
4. “Download a 30-second excerpt of that SatNOGS observation.”
5. “Explain this spectrogram, including what its axes mean.”
6. “Measure the first three seconds of the synthetic demo.”
7. “Compare these two recordings and explain why loudness can be misleading.”
8. “Find radio-frequency interference examples.”
9. “Create an evidence-based observation report in my configured report directory.”
10. “Check which sources are reachable without calling anything a live telescope.”