# dropbox-transcripts-mcp

An MCP server that indexes plain-text podcast transcripts stored in Dropbox and makes them searchable inside Claude Code. Syncs automatically as new transcripts are added.

## What it does

- Caches all `.txt` transcripts from a Dropbox folder into a local SQLite database with full-text search (FTS5)
- Polls Dropbox every N hours and indexes new or changed files automatically
- Exposes four tools to Claude Code: list, retrieve, search, and manual sync

## Prerequisites

- Python 3.10+
- [uv](https://docs.astral.sh/uv/getting-started/installation/) (`brew install uv` on macOS)
- A Dropbox account with your transcripts in a folder (default: `/Podcasts/Lenny`)

## Setup

### 1. Create a Dropbox app

1. Go to [https://www.dropbox.com/developers/apps](https://www.dropbox.com/developers/apps)
2. Click **Create app**
3. Choose **Scoped access** and **Full Dropbox**
4. Name it anything (e.g. `transcripts-mcp`)
5. Under the **Permissions** tab, enable:
   - `files.metadata.read`
   - `files.content.read`
6. Copy the **App Key** and **App Secret** from the Settings tab

### 2. Run the auth setup

```bash
uvx --from git+https://github.com/YOUR_USERNAME/dropbox-transcripts-mcp dropbox-transcripts-setup
```

This walks you through the OAuth flow and prints your `DROPBOX_REFRESH_TOKEN`. It will also print the exact MCP config block to paste into your Claude Code settings.

### 3. Add to Claude Code

Edit `~/.claude/settings.json` and add:

```json
{
  "mcpServers": {
    "transcripts": {
      "command": "uvx",
      "args": [
        "--from", "git+https://github.com/YOUR_USERNAME/dropbox-transcripts-mcp",
        "dropbox-transcripts-mcp"
      ],
      "env": {
        "DROPBOX_APP_KEY": "your_app_key",
        "DROPBOX_APP_SECRET": "your_app_secret",
        "DROPBOX_REFRESH_TOKEN": "your_refresh_token",
        "DROPBOX_FOLDER_PATH": "/Podcasts/Lenny"
      }
    }
  }
}
```

The first time Claude Code starts the server it will sync all transcripts from Dropbox. Subsequent syncs happen automatically in the background every 6 hours (configurable).

## Configuration

All configuration is via environment variables:

| Variable | Required | Default | Description |
|---|---|---|---|
| `DROPBOX_APP_KEY` | yes | | Dropbox app key |
| `DROPBOX_APP_SECRET` | yes | | Dropbox app secret |
| `DROPBOX_REFRESH_TOKEN` | yes | | OAuth refresh token |
| `DROPBOX_FOLDER_PATH` | no | `/Podcasts/Lenny` | Path to transcripts folder in Dropbox |
| `SYNC_INTERVAL_HOURS` | no | `6` | How often to poll Dropbox for changes |
| `DB_PATH` | no | `~/.dropbox-transcripts-mcp/transcripts.db` | Local SQLite database path |

## File naming convention

Transcript files should be named `Guest Name.txt`. The filename (without `.txt`) becomes the episode identifier used by `get_episode` and shown in `list_episodes`.

Examples: `Adam Fishman.txt`, `Elena Verna 2.0.txt`

## Available tools

| Tool | Description |
|---|---|
| `list_episodes_tool` | List all indexed episodes with last sync time |
| `get_episode_tool` | Get a full transcript by guest name (supports partial match) |
| `search_transcripts_tool` | Full-text search with highlighted snippets. Supports quoted phrases, AND/OR, prefix wildcards (`retain*`) |
| `sync_tool` | Manually trigger a Dropbox sync |

## License

MIT