# m3u8 MCP

m3u8 MCP Server - A desktop application that provides m3u8/HLS streaming capabilities through the Model Context Protocol (MCP), built with Tauri, React, and Rust.

![m3u8 MCP Dashboard](docs/images/dashboard.png)

📝 **Related article**: [Understanding m3u8 files and FFmpeg streaming (Japanese)](https://qiita.com/yonaka15/items/09d41f722fa226c2d48c)

## 🚀 Features

### Core Features
- **MCP Server**: Streamable HTTP server using Axum on configurable port (default: 37650)
- **m3u8 Parsing**: Full support for parsing HLS playlists (master and media playlists)
- **FFmpeg Integration**: Download and convert streaming media using FFmpeg
- **Segment Extraction**: Extract and display all segment URLs from playlists
- **Internationalization**: Support for English and Japanese languages
- **Persistent Configuration**: Securely stores settings locally (~/.m3u8-mcp/config.json)
- **Cross-Platform**: Works on macOS, Windows, and Linux

### Advanced Features 🎉
- **Folder Selection Dialog**: Choose download destination with native OS dialog
- **Download Progress**: Real-time download progress tracking with speed and size info
- **URL History**: Automatic tracking of recently used m3u8 URLs
- **Segment Display**: View and copy individual segment URLs with pagination
- **Content Disclaimer**: Built-in disclaimer system for responsible usage
- **Menu System**: Clean hamburger menu for settings organization
- **MCP Status Indicator**: Visual indicator for MCP server connection status
- **Local SQLite Cache**: Store parsed playlists and metadata for offline access

## 📋 Prerequisites

- Node.js (v16 or higher)
- Rust (latest stable)
- npm/pnpm/yarn
- FFmpeg installed on your system
- Your favorite AI assistant with MCP support (Claude, Cursor, etc.)

## 🛠️ Installation

1. Clone the repository:

```bash
git clone https://github.com/yourusername/m3u8-mcp.git
cd m3u8-mcp
```

2. Install dependencies:

```bash
npm install
```

3. Start the development server:

```bash
npm run tauri dev
```

## 🎮 Usage

### Setting up FFmpeg Path

1. **Configure FFmpeg**:
   - Click the menu button (☰) in the top-left corner
   - Select "FFmpeg Configuration"
   - Enter the path to your FFmpeg binary (or use system FFmpeg if in PATH)

2. **Start the MCP Server**:
   - Click the menu button (☰) or the MCP status indicator
   - Select "MCP Server Control"
   - Choose your port and click "Connect to AI via MCP"
   - Copy the connection command for your AI assistant

### User Interface Features

- **Language Toggle**: Switch between English and Japanese (EN/JP button)
- **URL Management**: Clear button and history dropdown for quick access
- **Three Main Operations**:
  - Parse Playlist: Analyze m3u8 structure and variants
  - Extract Segments: Get all segment URLs with copy functionality
  - Download Stream: Save stream with folder selection dialog
- **Collapsible Results**: Each result section has an X button for dismissal
- **Pagination**: "Show More" and "Show Less" buttons for segment lists

### Running as MCP Server

The application runs as an MCP Streamable HTTP server using Axum:

```bash
cargo run --release --manifest-path src-tauri/Cargo.toml
```

### Connect with Claude Code

```bash
claude mcp add --transport http m3u8 http://localhost:37650/mcp
```

### Connect with Claude Desktop

Add to your Claude Desktop configuration:

```json
{
  "m3u8": {
    "command": "npx",
    "args": [
      "-y",
      "mcp-remote",
      "http://localhost:37650/mcp"
    ]
  }
}
```

## 🔧 Available MCP Tools

### URL Management

#### m3u8_set_url
Set the current m3u8 URL in the UI.

**Parameters:**
- `url` (string, required): URL to set in the UI

#### m3u8_get_url
Get the current m3u8 URL from the UI.

### Parsing Tools

#### m3u8_parse
Parse an m3u8 playlist and extract information.

**Parameters:**
- `url` (string): URL of the m3u8 playlist
- `content` (string): Raw m3u8 content (if URL not provided)

#### m3u8_extract_segments
Extract all segment URLs from a playlist.

**Parameters:**
- `url` (string): URL of the m3u8 playlist
- `base_url` (string): Base URL for relative segment URLs

### Download Tools

#### m3u8_download
Download a complete stream using FFmpeg.

**Parameters:**
- `url` (string, required): URL of the m3u8 stream
- `output_path` (string, required): Output file path
- `format` (string): Output format (mp4, mkv, ts, default: mp4)

### Conversion Tools

#### m3u8_convert
Convert a video file to HLS format.

**Parameters:**
- `input_path` (string, required): Path to input video
- `output_dir` (string, required): Output directory for HLS files
- `segment_duration` (number): Duration of each segment in seconds (default: 10)
- `playlist_type` (string): Playlist type (vod or event, default: vod)

### Probe Tools

#### m3u8_probe
Probe m3u8 stream for information using FFmpeg.

**Parameters:**
- `url` (string, required): URL of the m3u8 stream

### Cache Management

#### m3u8_cache_list
List cached playlists and downloads.

**Parameters:**
- `query` (string): Optional search query
- `limit` (number): Maximum results (default: 100)

#### m3u8_cache_clear
Clear all cached data.

## 🏗️ Tech Stack

### Frontend

- **React 19** - UI framework
- **TypeScript** - Type safety
- **Tailwind CSS v4** - Styling
- **Vite** - Build tool
- **@tauri-apps/api** - Tauri integration
- **video.js** - Stream preview

### Backend

- **Rust** - Core backend language
- **Tauri v2** - Desktop application framework
- **Axum** - Web framework for MCP Streamable HTTP server
- **Reqwest** - HTTP client for downloading
- **Rusqlite** - SQLite database for caching
- **Tokio** - Async runtime
- **Tower-http** - CORS and middleware support

### External Dependencies

- **FFmpeg** - Media processing and conversion
- **m3u8-parser** - Playlist parsing library

### Protocol

- **MCP Streamable HTTP** - HTTP/SSE transport with Axum
- **JSON-RPC 2.0** - Message format
- **Server-Sent Events (SSE)** - Real-time server-to-client streaming
- **HLS (HTTP Live Streaming)** - Adaptive bitrate streaming protocol

## 📁 Project Structure

```
m3u8-mcp/
├── src/                      # React frontend
│   ├── App.tsx              # Main UI with menu system
│   ├── components/
│   │   └── M3u8Form.tsx     # m3u8 operations and display
│   └── i18n.ts              # Internationalization (EN/JP)
│   ├── components/          
│   │   └── StreamViewer.tsx # Stream preview component
│   ├── i18n.ts              # Language translations (EN/JP)
│   └── main.tsx             # Application entry point
├── src-tauri/               # Rust backend
│   ├── src/
│   │   ├── lib.rs           # Tauri commands & server lifecycle
│   │   ├── mcp_server.rs    # MCP Streamable HTTP server (Axum)
│   │   ├── m3u8_client.rs   # m3u8 parsing and operations
│   │   ├── ffmpeg_wrapper.rs # FFmpeg integration
│   │   └── database.rs      # SQLite cache management
│   ├── Cargo.toml           # Rust dependencies
│   └── tauri.conf.json      # Tauri configuration
├── package.json             # Node.js dependencies
├── vite.config.ts           # Vite configuration
└── README.md               # This file
```

## 🔨 Build

Build the application for production:

```bash
npm run tauri build
```

The built application will be available in:

- **macOS**: `src-tauri/target/release/bundle/dmg/`
- **Windows**: `src-tauri/target/release/bundle/msi/`
- **Linux**: `src-tauri/target/release/bundle/appimage/`

## 🧪 Testing

Test the MCP server with example m3u8 streams:

```bash
# Parse a playlist
curl -X POST http://localhost:37650/mcp \
  -H "Content-Type: application/json" \
  -d '{"method": "m3u8_parse_playlist", "params": {"url": "https://example.com/stream.m3u8"}}'

# Download a stream
curl -X POST http://localhost:37650/mcp \
  -H "Content-Type: application/json" \
  -d '{"method": "m3u8_download", "params": {"url": "https://example.com/stream.m3u8", "output_path": "output.mp4"}}'
```

## 🦀 Why Rust?

This project leverages Rust for the same reasons as the original Redmine MCP:

### Performance
- **Native Speed** - Compiled to machine code for maximum performance
- **Zero-Cost Abstractions** - High-level code without runtime overhead
- **Efficient Memory Usage** - Critical for handling large video streams

### Reliability
- **Memory Safety** - Prevents segfaults and memory leaks at compile time
- **Thread Safety** - Concurrent segment downloads without data races
- **Error Handling** - Robust Result types for network and file operations

### Integration
- **Axum** - Modern async web framework for HTTP/SSE
- **Tokio** - Powerful async runtime for concurrent operations
- **FFmpeg** - Seamless integration with system FFmpeg

## 🚧 Roadmap

- [x] MCP Streamable HTTP server with Axum
- [x] Basic m3u8 parsing
- [x] FFmpeg integration for downloads
- [ ] Multi-bitrate stream support
- [ ] Live stream recording
- [ ] Stream preview in UI
- [ ] Segment-level operations
- [ ] Advanced playlist generation
- [ ] Scheduled recordings
- [ ] Stream quality analysis
- [ ] DRM content handling (where legal)
- [ ] Cloud storage integration
- [ ] Batch processing
- [ ] Stream monitoring dashboard

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

## 📝 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- [Tauri](https://tauri.app/) - For the amazing desktop framework
- [MCP Specification](https://spec.modelcontextprotocol.io/) - For the protocol documentation
- [FFmpeg](https://ffmpeg.org/) - For powerful media processing capabilities
- [Axum](https://github.com/tokio-rs/axum) - For the excellent web framework
- Original [Redmine MCP](https://github.com/yonaka15/redmine-mcp) project for the modular architecture

## 📞 Support

For issues and questions:
- Open an issue on GitHub
- Check the related [Qiita article](https://qiita.com/yonaka15/items/09d41f722fa226c2d48c) for m3u8/FFmpeg details

---

**Note**: Ensure FFmpeg is installed and accessible on your system before using this application. Be mindful of copyright and legal considerations when downloading streaming content.