Audio MCP Server

Modularer Model Context Protocol (MCP) Server für plattformübergreifenden Audio-Hardware-Zugriff. Ermöglicht KI-Assistenten wie Claude Desktop die Steuerung von Audiogeräten, Aufnahme, Wiedergabe, Analyse, Text-Vorlesen und Spracherkennung.

Features

Bereich	Beschreibung
Geräte-Verwaltung	Ein-/Ausgabegeräte auflisten & auswählen
Aufnahme	Einzelaufnahmen und kontinuierliche Aufnahme mit Ringpuffer
Wiedergabe	Audio abspielen mit Steuerung (Pause, Stop, Seek)
Lautstärke	Plattformübergreifend (Windows pycaw, macOS osascript, Linux pactl)
Echtzeit-Streaming	WebSocket-basiertes Audio-Streaming
Analyse	Spektralanalyse (FFT, Mel/MFCC), Pegelanalyse, VAD
Text-Vorlesen	Webseiten, PDFs, Textdateien via TTS vorlesen (NEU v0.2)
Spracherkennung	Audiodateien & Mikrofon transkribieren, Sprachbefehle (NEU v0.2)
Plugins	BirdSound, Soundscape, Ambient Guide, ProAudio, MIDI, Reader, Speech
Sicherheit	Capability-basierte Berechtigungen, Consent-System, Audit-Log

Dokumentation

Dokument	Beschreibung
README.md	Diese Übersicht
CHANGELOG.md	Versionshistorie
INSTALLATION.md	Detaillierte Installationsanleitung
docs/analysis.md	Spektralanalyse & Visualisierung
docs/plugins/reader.md	Plugin: Reader (Text vorlesen)
docs/plugins/speech.md	Plugin: Speech (Spracherkennung)
docs/plugins/birdsound.md	Plugin: BirdSound (Vogelstimmen) — siehe auch Birds
docs/plugins/soundscape.md	Plugin: Soundscape (Umgebungsklang-Analyse)
docs/plugins/ambient-guide.md	Plugin: Ambient Guide (Umgebungs-Analyse & Audio-Guide)
docs/plugins/proaudio.md	Plugin: ProAudio (Diagnose & Metering)

Schnellstart

Voraussetzungen

Python 3.11+ (getestet bis 3.14)
ffmpeg — für Audio-Konvertierung
PortAudio — für Echtzeit-Audio-I/O (wird über sounddevice mitgeliefert)

1. Repository klonen

git clone https://github.com/donapart/Audio-mcp.git
cd Audio-mcp

2. Automatische Installation (empfohlen)

# Windows (PowerShell)
.\setup.ps1

# macOS / Linux
chmod +x setup.sh && ./setup.sh

Das Setup-Skript:

Erstellt ein virtuelles Environment (.venv)
Installiert alle Basis- und Dev-Abhängigkeiten
Prüft System-Abhängigkeiten (ffmpeg, PortAudio)
Verifiziert die Installation

3. Manuelle Installation

# Virtuelles Environment erstellen
python -m venv .venv

# Aktivieren
.\.venv\Scripts\Activate.ps1    # Windows PowerShell
source .venv/bin/activate        # macOS / Linux

# Basis + Entwicklung
pip install -e ".[dev]"

4. Optionale Features installieren

# Text-Vorlesen (TTS + Webseiten + PDFs)
pip install -e ".[edge-tts,reader]"

# Spracherkennung (STT)
pip install -e ".[stt]"

# Alles auf einmal
pip install -e ".[edge-tts,reader,stt,analysis,streaming,windows]"

Vollständige Übersicht aller optionalen Pakete: → INSTALLATION.md

Verfügbare optionale Pakete

Extra	Pakete	Beschreibung
`edge-tts`	edge-tts, pydub	Microsoft Edge TTS (empfohlen für Python 3.12+)
`tts`	Coqui TTS	Lokale TTS mit XTTS v2 (nur Python ≤3.11)
`stt`	SpeechRecognition	Spracherkennung (Google Cloud)
`stt-whisper`	faster-whisper	Lokale Whisper-Transkription
`stt-vosk`	Vosk	Offline-Spracherkennung
`reader`	trafilatura, bs4, pymupdf	Webseiten- & PDF-Textextraktion
`reader-minimal`	beautifulsoup4	Nur Webseiten-Extraktion
`analysis`	librosa	Erweiterte Audio-Analyse
`visualization`	matplotlib	Spektrogramm-Visualisierung
`streaming`	websockets	WebSocket-Audio-Streaming
`proaudio`	pyloudnorm, pedalboard	Professionelles Audio-Metering
`midi`	mido, python-rtmidi	MIDI-Geräte-Steuerung
`birdsound`	BirdNET	Vogelstimmen-Erkennung — Birds
`vad`	webrtcvad	Voice Activity Detection
`windows`	pycaw	Windows-Lautstärkeregelung

Verwendung

Stdio-Transport (für Claude Desktop)

audio-mcp
# oder
python -m audio_mcp.server

Streamable HTTP Transport

audio-mcp --transport streamable-http --port 8765

Claude Desktop Konfiguration

Die Datei claude_desktop_config.json ergänzen:

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "audio": {
      "command": "D:/Projekte/Audio-mcp/.venv/Scripts/python",
      "args": ["-m", "audio_mcp.server"],
      "env": {
        "AUDIO_MCP_CONFIG": "D:/Projekte/Audio-mcp/config/default.yaml"
      }
    }
  }
}

Oder mit dem Konfigurationsskript:

.\scripts\setup_claude_config.ps1

MCP-Tools Übersicht

Core Tools

Tool	Beschreibung
`list_audio_devices`	Alle Audio-Ein-/Ausgabegeräte anzeigen
`record_audio`	Audio aufnehmen (Dauer, Format, Gerät wählbar)
`play_audio`	Audiodatei abspielen
`stop_playback`	Wiedergabe stoppen
`set_volume` / `get_volume`	Systemlautstärke steuern
`generate_tone`	Künstlichen Ton erzeugen
`generate_noise`	Rauschen erzeugen (Weiß, Rosa, Braun)
`generate_binaural`	Binaural-Beats erzeugen

Analyse Tools

Tool	Beschreibung
`analyze_spectrum`	FFT / Mel-Spektrogramm / MFCC
`analyze_levels`	RMS, Peak, LUFS Pegelanalyse
`detect_voice_activity`	Sprachaktivitäts-Erkennung
`compare_audio`	Audio-Similarity-Vergleich

Reader Tools (NEU v0.2)

Tool	Beschreibung
`read_aloud`	Webseite, PDF oder Text vorlesen
`extract_text`	Text aus Quelle extrahieren (ohne Sprache)
`speak_text`	Beliebigen Text als Audio synthetisieren
`read_webpage`	Webseite vorlesen (Shortcut)
`read_pdf`	PDF-Datei vorlesen (Shortcut)
`list_tts_voices`	Verfügbare TTS-Stimmen auflisten

Speech Tools (NEU v0.2)

Tool	Beschreibung
`transcribe_audio`	Audiodatei → Text
`transcribe_microphone`	Mikrofonaufnahme → Text
`listen_for_command`	Auf Sprachbefehl lauschen (mit Stille-Erkennung)
`list_stt_backends`	Verfügbare STT-Backends anzeigen

Docker

# Build
docker build -t audio-mcp-server .

# Run (HTTP-Transport)
docker run -p 8765:8765 audio-mcp-server

# Mit Audio-Gerät (Linux)
docker run -p 8765:8765 --device /dev/snd audio-mcp-server

Konfiguration

Datei	Beschreibung
`config/default.yaml`	Server-Einstellungen, Audio-Defaults, Plugin-Aktivierung
`config/permissions.yaml`	Capability-basierte Berechtigungen
`config/plugins/*.yaml`	Plugin-spezifische Konfiguration

Umgebungsvariablen

Variable	Beschreibung	Standard
`AUDIO_MCP_CONFIG`	Pfad zur Konfigurations-YAML	`config/default.yaml`
`AUDIO_MCP_STORAGE_DIR`	Audio-Speicherverzeichnis	System-Temp

Entwicklung

Tests ausführen

# Alle Tests
pytest

# Mit Coverage
pytest --cov=audio_mcp --cov-report=html

# Nur bestimmte Module
pytest tests/test_core/
pytest tests/test_plugins/test_reader/
pytest tests/test_plugins/test_speech/

Code-Qualität

ruff check src/ tests/      # Linting
ruff format src/ tests/      # Formatierung
mypy src/audio_mcp/          # Type-Checking

Audio-Geräte testen

python scripts/test_audio_devices.py

Projektstruktur

Audio-mcp/
├── config/                  # Konfigurationsdateien
│   ├── default.yaml         # Server & Plugin-Einstellungen
│   ├── permissions.yaml     # Berechtigungen
│   └── plugins/             # Plugin-spezifische Configs
├── docs/                    # Dokumentation
│   ├── analysis.md
│   └── plugins/
│       ├── reader.md        # Reader-Plugin Doku
│       ├── speech.md        # Speech-Plugin Doku
│       └── ...
├── scripts/                 # Installations- & Hilfs-Skripte
├── src/audio_mcp/
│   ├── __init__.py          # Version: 0.2.0
│   ├── app.py               # FastMCP-Instanz & Lifespan
│   ├── server.py            # Einstiegspunkt & CLI
│   ├── models.py            # Pydantic-Modelle
│   ├── core/                # Geräte, Aufnahme, Wiedergabe, Volume, Stream
│   │   ├── tts_service.py   # Gemeinsamer TTS-Service (edge-tts/Coqui)
│   │   ├── stt_service.py   # STT-Service (Whisper/SR/Vosk)
│   │   └── ...
│   ├── analysis/            # Spektrum, Pegel, VAD, Embeddings
│   ├── plugins/
│   │   ├── reader/          # Text-Vorlesen (NEU v0.2)
│   │   ├── speech/          # Spracherkennung (NEU v0.2)
│   │   ├── birdsound/       # Vogelstimmen-Erkennung (BirdNET)
│   │   ├── soundscape/      # Umgebungsklang-Analyse
│   │   ├── ambient_guide/   # Umgebungs-Analyse & Audio-Guide
│   │   ├── proaudio/        # Professionelles Metering
│   │   └── midi/            # MIDI-Steuerung
│   ├── security/            # Permissions, Consent, Audit
│   ├── tools/               # MCP-Tool-Registrierung
│   └── utils/               # Config, File-Manager, Helpers
├── tests/                   # pytest-Testsuite
├── CHANGELOG.md             # Versionshistorie
├── INSTALLATION.md          # Installationsanleitung
├── Dockerfile               # Multi-Stage Docker Build
├── setup.ps1                # Windows Setup-Skript
├── setup.sh                 # Linux/macOS Setup-Skript
└── pyproject.toml           # Build-Konfiguration (hatchling)

Entwicklung & Autor

Entwickelt von Dano Schönwald — github.com/donapart

Unterstützen / Donate

Wenn dir dieses Projekt gefällt, kannst du mich gerne unterstützen:

Methode	Link
PayPal	paypal.me/danoschoenwald
Revolut	@dano_s
GitHub Sponsors	github.com/sponsors/donapart

Lizenz

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 7 Commits
.github		.github
config		config
docs		docs
scripts		scripts
src/audio_mcp		src/audio_mcp
tests		tests
.dockerignore		.dockerignore
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
CHANGELOG.md		CHANGELOG.md
Dockerfile		Dockerfile
IMPLEMENTATION_PLAN.md		IMPLEMENTATION_PLAN.md
INSTALLATION.md		INSTALLATION.md
README.md		README.md
audio-mcp-plan.md		audio-mcp-plan.md
pyproject.toml		pyproject.toml
setup.ps1		setup.ps1
setup.sh		setup.sh

Folders and files

Latest commit

History

Repository files navigation

Audio MCP Server

Features

Dokumentation

Schnellstart

Voraussetzungen

1. Repository klonen

2. Automatische Installation (empfohlen)

3. Manuelle Installation

4. Optionale Features installieren

Verfügbare optionale Pakete

Verwendung

Stdio-Transport (für Claude Desktop)

Streamable HTTP Transport

Claude Desktop Konfiguration

MCP-Tools Übersicht

Core Tools

Analyse Tools

Reader Tools (NEU v0.2)

Speech Tools (NEU v0.2)

Docker

Konfiguration

Umgebungsvariablen

Entwicklung

Tests ausführen

Code-Qualität

Audio-Geräte testen

Projektstruktur

Entwicklung & Autor

Unterstützen / Donate

Lizenz

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages