<div align="center">

# 🗂️ mega-mcp

### Turn any public [MEGA](https://mega.nz) folder into a knowledge source for Claude & other LLMs

**Browse · Search · Read files & PDFs · Video metadata · Optional transcription** — all from a public `mega.nz` link, no account required.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Node](https://img.shields.io/badge/node-%E2%89%A518-43853d.svg)](https://nodejs.org)
[![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6.svg)](https://www.typescriptlang.org/)
[![MCP](https://img.shields.io/badge/Model_Context_Protocol-server-6E56CF.svg)](https://modelcontextprotocol.io)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](#-contributing)

⭐ **If this saves you time, please star the repo — it really helps others find it.**

</div>

---

## What is this?

**mega-mcp** is a [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that exposes a **public MEGA folder or file link** as a queryable knowledge base. Point it at a share link and your AI assistant — [Claude Code](https://claude.com/claude-code), Claude Desktop, or any MCP-compatible client — can browse the tree, search filenames, read text files and **extract text from PDFs**, inspect video/audio metadata, and **optionally transcribe** media to text.

No MEGA login. No re-uploading your files somewhere else. Just a link.

> Great for course libraries, research archives, documentation dumps, datasets, meeting recordings — any pile of files already living on MEGA that you want an LLM to actually *use*.

## ✨ Features

| | Tool | What it does |
|---|---|---|
| 📁 | **`mega_browse`** | List a folder link — top level, a subfolder, or the entire tree. |
| 🔎 | **`mega_search`** | Find files/folders by name across the whole share (substring or regex). |
| 📄 | **`mega_read_file`** | Return a file's text. **PDFs are auto-extracted to text.** Other binaries are rejected. |
| 🧠 | **`mega_search_content`** | Full-text search *inside* text files **and PDFs**, with line-level snippets. |
| 🎬 | **`mega_video_info`** | Video/audio metadata (duration, resolution, codecs, fps, bitrate) — streams only the header, no full download. |
| 🎙️ | **`mega_transcribe`** | *(opt-in)* Transcribe speech to text via a pluggable backend (OpenAI-compatible API **or** any local CLI like whisper.cpp). |

- 🔓 **Public links only** — folder links and single-file links, zero credentials.
- 📦 **Batteries included** — `ffmpeg`/`ffprobe` ship via npm; PDF extraction uses a bundled pdf.js. No system installs.
- 🧩 **Pluggable transcription** — bring OpenAI Whisper, a local model, or any command. Off by default.
- ⏱️ **Long-job friendly** — emits MCP progress so big transcriptions don't hit client timeouts.
- 🛡️ **Safe by default** — size caps, binary detection, and friendly errors for dead/blocked/expired links.

## 📑 Table of contents

- [Quick start](#-quick-start)
- [Use with Claude Code](#-use-with-claude-code)
- [Use with Claude Desktop](#-use-with-claude-desktop)
- [Configuration](#%EF%B8%8F-configuration)
- [Transcription (optional)](#-transcription-optional)
- [Tool reference & example prompts](#-tool-reference--example-prompts)
- [How it works](#-how-it-works)
- [FAQ](#-faq)
- [Roadmap](#-roadmap)
- [Contributing](#-contributing)
- [License](#-license)

## 🚀 Quick start

```bash
git clone https://github.com/Anicodeth/mega-mcp.git
cd mega-mcp
npm install
npm run build
```

That's it — `dist/index.js` is your MCP server. Wire it into a client below.

## 🤖 Use with Claude Code

```bash
claude mcp add mega \
  -e MEGA_LINK="https://mega.nz/folder/XXXX#YYYY" \
  -- node "/absolute/path/to/mega-mcp/dist/index.js"
```

Then just ask: *"Browse my MEGA folder and summarize what's in the Strategy section."*

> On Windows, use the full path, e.g. `node "C:\\path\\to\\mega-mcp\\dist\\index.js"`.

## 🖥️ Use with Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "mega": {
      "command": "node",
      "args": ["/absolute/path/to/mega-mcp/dist/index.js"],
      "env": {
        "MEGA_LINK": "https://mega.nz/folder/XXXX#YYYY"
      }
    }
  }
}
```

Without `MEGA_LINK`, pass a `link` argument to each tool call instead — handy for working with many links.

## ⚙️ Configuration

All environment variables are optional.

| Var | Purpose | Default |
| --- | --- | --- |
| `MEGA_LINK` | Default public link so tools work without repeating it. Per-call `link` args override it. | — |
| `MEGA_MAX_READ_BYTES` | Max bytes to download for a text-file read / content search. | `2000000` |
| `MEGA_MAX_PDF_BYTES` | Max bytes to download for a PDF before extracting text. | `25000000` |

## 🎙️ Transcription (optional)

`mega_transcribe` is **off by default**. Turn it on by choosing a backend.

<details open>
<summary><b>Option A — OpenAI-compatible API (Whisper, etc.)</b></summary>

| Var | Value |
| --- | --- |
| `MEGA_TRANSCRIBE` | `openai` |
| `OPENAI_API_KEY` | your key *(required)* |
| `OPENAI_BASE_URL` | optional, default `https://api.openai.com/v1` |
| `MEGA_TRANSCRIBE_MODEL` | optional, default `whisper-1` |

Works with any OpenAI-compatible endpoint (Groq, local servers, etc.) via `OPENAI_BASE_URL`.
</details>

<details>
<summary><b>Option B — Local / custom command (no API key)</b></summary>

| Var | Value |
| --- | --- |
| `MEGA_TRANSCRIBE` | `command` |
| `MEGA_TRANSCRIBE_CMD` | a shell command where `{input}` is replaced by an audio-chunk path; its **stdout** is taken as the transcript. |

A ready-to-use [faster-whisper](https://github.com/SYSTRAN/faster-whisper) wrapper is included at [`scripts/whisper_cli.py`](scripts/whisper_cli.py):

```bash
pip install faster-whisper
```

```bash
# macOS/Linux
export MEGA_TRANSCRIBE=command
export MEGA_TRANSCRIBE_CMD='python /path/to/mega-mcp/scripts/whisper_cli.py {input}'
export WHISPER_MODEL=base   # tiny | base | small | medium | large-v3
```

The wrapper runs fully locally on CPU — no API key, no data leaving your machine.
</details>

**How it works:** the media file is downloaded to a temp dir, `ffmpeg` (bundled) extracts mono 16 kHz audio and splits it into ~10-minute segments, each segment goes to your backend, and results are concatenated. Use the `maxMinutes` argument to transcribe just the start of a long file.

## 🛠️ Tool reference & example prompts

Once connected, you can drive everything in natural language:

| You say… | Tool used |
| --- | --- |
| *"What folders are in my MEGA share?"* | `mega_browse` |
| *"Find every file with 'invoice' in the name."* | `mega_search` |
| *"Read `Strategy/onboarding.md` and summarize it."* | `mega_read_file` |
| *"Open the Patreon case study PDF and pull the key takeaways."* | `mega_read_file` (PDF) |
| *"Search all the PDFs for 'activation metric' and show me where."* | `mega_search_content` |
| *"How long is `lecture-03.mp4` and what resolution?"* | `mega_video_info` |
| *"Transcribe the first 10 minutes of `lecture-03.mp4`."* | `mega_transcribe` |

<details>
<summary>Argument details</summary>

- **`mega_browse`** — `link?`, `path?` (subfolder), `recursive?` (default `false`)
- **`mega_search`** — `query`, `link?`, `regex?`, `filesOnly?`
- **`mega_read_file`** — `path?` *or* file `link`, `maxBytes?`
- **`mega_search_content`** — `query`, `link?`, `regex?`, `includePdf?` (default `true`), `maxFiles?`, `maxMatchesPerFile?`
- **`mega_video_info`** — `path?` *or* file `link`, `raw?`
- **`mega_transcribe`** — `path?` *or* file `link`, `maxMinutes?`, `language?`, `segmentMinutes?`

Every tool falls back to `MEGA_LINK` when `link` is omitted.
</details>

## 🔬 How it works

```
            public MEGA link
                   │
        ┌──────────▼───────────┐
        │  megajs (no login)   │  load link → walk tree → resolve path → download
        └──────────┬───────────┘
                   │
   ┌───────────────┼───────────────────────────┐
   ▼               ▼                ▼            ▼
 browse /        read_file /      video_info   transcribe (opt-in)
 search          search_content   (ffprobe,    (download → ffmpeg
 (metadata)      (text + PDF via   header-only)  audio segments →
                  unpdf/pdf.js)                   backend → text)
```

- **Public links** are resolved with [megajs](https://github.com/qgustavor/mega) — both `/folder/…#key` and `/file/…#key` forms.
- **PDFs** are extracted with [unpdf](https://github.com/unjs/unpdf) (a serverless-friendly pdf.js build). Scanned/image-only PDFs yield no text (OCR not included).
- **Video metadata** is read by streaming only the header into `ffprobe` — a 1 GB file is probed in seconds without downloading it.
- **Transcription** downloads the file (needed because many mp4s store their index at the end and pipes aren't seekable), then segments audio so even hour-long lectures stay within backend size limits.

## ❓ FAQ

**Do I need a MEGA account?** No. mega-mcp only uses public share links.

**Does it support private/account files?** Not currently — public links only, by design. See the [roadmap](#-roadmap).

**Are my files re-uploaded anywhere?** No. Files are fetched directly from MEGA on demand. With the local transcription backend, nothing leaves your machine.

**Can it read Word/Excel/PowerPoint?** Not yet — text files and PDFs today. Office formats are on the roadmap.

**Will big transcriptions time out in my client?** The server emits MCP progress notifications, which keeps compatible clients alive. Use `maxMinutes` to cap long files.

**Does `ffmpeg` need to be installed?** No — `ffmpeg-static` and `ffprobe-static` bundle the binaries.

## 🗺️ Roadmap

- [ ] Optional account login for private files
- [ ] Office document extraction (`docx`, `xlsx`, `pptx`)
- [ ] OCR for scanned PDFs / images
- [ ] Cached content index for faster repeated searches
- [ ] Resource endpoints (expose files as MCP resources)

Have an idea? [Open an issue](https://github.com/Anicodeth/mega-mcp/issues) 🙌

## 🤝 Contributing

Contributions are very welcome!

```bash
npm install
npm run build      # compile
npm run typecheck  # strict type check
npm run dev        # watch mode
```

1. Fork the repo and create a feature branch.
2. Keep the code style consistent and types strict.
3. Open a PR describing the change. Small, focused PRs are easiest to merge.

If you find a bug or want a feature, [issues](https://github.com/Anicodeth/mega-mcp/issues) and ⭐ stars are both hugely appreciated.

## 📁 Project layout

```
src/
  index.ts       MCP server + tool definitions
  mega.ts        megajs wrapper (load link, walk tree, resolve path, download)
  pdf.ts         PDF text extraction (unpdf)
  video.ts       ffprobe streaming + metadata distillation
  transcribe.ts  optional, pluggable audio/video transcription
  types.d.ts     ambient module declaration for ffprobe-static
scripts/
  whisper_cli.py local faster-whisper transcription backend
```

## 📜 License

[MIT](LICENSE) © [Ananya Fekeremariam (Anicodeth)](https://github.com/Anicodeth)

---

<div align="center">

Built with the [Model Context Protocol](https://modelcontextprotocol.io). If it helped, drop a ⭐ — thank you!

</div>