# MCP Audio RAG Server

> Transform your audio files into a searchable knowledge base using AI. Ask Claude questions about your meetings, podcasts, lectures, or any audio content.

<p align="center">
  <a href="https://www.buymeacoffee.com/matheusslg" target="_blank">
    <img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" height="50">
  </a>
</p>

## What is this?

This is an MCP (Model Context Protocol) server that lets you:

1. **Transcribe** any audio file using Google's Gemini AI
2. **Store** the transcriptions in a searchable database
3. **Search** through all your audio content using natural language

Once set up, you can simply ask Claude things like:
- *"What did they discuss about the budget in my meeting recording?"*
- *"Find mentions of machine learning in my podcast collection"*
- *"What were the key points from yesterday's lecture?"*

## How It Works

```
┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│ Audio File  │ ──▶ │   Gemini    │ ──▶ │  Chunking   │ ──▶ │  Supabase   │
│ (.mp3, etc) │     │ Transcribe  │     │ + Embedding │     │  (pgvector) │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘
                                                                   │
┌─────────────┐     ┌─────────────┐     ┌─────────────┐            │
│   Claude    │ ◀── │   Results   │ ◀── │   Search    │ ◀──────────┘
│  Response   │     │ + Snippets  │     │   Query     │
└─────────────┘     └─────────────┘     └─────────────┘
```

## Quick Start

### Prerequisites

- **Node.js 18+** - [Download here](https://nodejs.org/)
- **Gemini API Key** - [Get one free](https://aistudio.google.com/apikey)
- **Supabase Account** - [Sign up free](https://supabase.com)

### Step 1: Clone & Install

```bash
git clone https://github.com/matheusslg/mcp-audio-rag.git
cd mcp-audio-rag
npm install
```

### Step 2: Set Up Supabase Database

1. Create a new project at [supabase.com](https://supabase.com)
2. Go to **SQL Editor** in your dashboard
3. Paste and run the contents of `supabase/schema.sql`

### Step 3: Get Your API Keys

**Supabase** (Settings → API):
- Copy **Project URL** → `SUPABASE_URL`
- Copy **service_role key** → `SUPABASE_SERVICE_KEY`

**Google AI Studio**:
- Create key at [aistudio.google.com/apikey](https://aistudio.google.com/apikey) → `GEMINI_API_KEY`

### Step 4: Configure

```bash
cp .env.example .env
```

Edit `.env`:
```
GEMINI_API_KEY=your-key-here
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_KEY=your-service-role-key
```

### Step 5: Add to Claude

**For Claude Code CLI** (`~/.claude.json`):

```json
{
  "mcpServers": {
    "audio-rag": {
      "command": "npx",
      "args": ["tsx", "/full/path/to/mcp-audio-rag/src/server.ts"],
      "env": {
        "GEMINI_API_KEY": "your-key",
        "SUPABASE_URL": "https://your-project.supabase.co",
        "SUPABASE_SERVICE_KEY": "your-service-role-key"
      }
    }
  }
}
```

**For Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json` on Mac):

Same config as above.

## Usage

### Transcribe Audio

Just tell Claude to transcribe a file:

```
Transcribe /path/to/meeting.mp3
```

Want to use a specific model? Just ask:

```
Transcribe /path/to/lecture.m4a using gemini-2.5-pro
```

### Search Your Audio

Ask natural questions:

```
What did they say about the project timeline?
Search for mentions of "budget" in my recordings
Find discussions about AI in my podcasts
```

### Manage Your Library

```
List all my transcribed audio files
Delete the recording from last week
Get the full transcript of meeting.mp3
Summarize the podcast episode
```

## Available Models

| Model | Best For |
|-------|----------|
| `gemini-2.5-flash` | **Default** - Fast & accurate, great balance |
| `gemini-2.5-flash-lite` | Fastest, cheapest - good for bulk processing |
| `gemini-2.5-pro` | Best quality - complex audio, multiple speakers |
| `gemini-3-pro-preview` | Newest - cutting edge capabilities |
| `gemini-2.0-flash` | Reliable - previous generation |
| `gemini-2.0-flash-lite` | Fast - previous generation |

## Supported Audio Formats

`.mp3` `.mp4` `.m4a` `.wav` `.webm` `.mpeg` `.mpga`

## Available Tools

| Tool | Description |
|------|-------------|
| `ingest_audio` | Transcribe and store an audio file |
| `search_transcripts` | Search through your audio using natural language |
| `list_transcripts` | List all transcribed audio files |
| `get_full_transcript` | Get the complete transcript of a file |
| `summarize_audio` | Generate an AI summary of a transcript |
| `delete_transcript` | Remove a transcribed file from the database |

## Troubleshooting

| Problem | Solution |
|---------|----------|
| "No relevant segments found" | Try rephrasing your search, or check if audio was ingested |
| "Missing environment variable" | Check your `.env` file or Claude config has all 3 keys |
| Supabase errors | Make sure you're using `service_role` key, not `anon` key |
| Slow transcription | Use `gemini-2.5-flash-lite` for faster processing |

## Support This Project

If this project saved you time or helped you out, consider buying me a coffee!

<a href="https://www.buymeacoffee.com/matheusslg" target="_blank">
  <img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" height="50">
</a>

## License

MIT - Use it however you want!

---

<p align="center">
  Made with Gemini + Supabase + Claude
</p>