<div align="center">

🗂️ mega-mcp

Turn any public MEGA 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.

⭐ 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 (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, 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
• Use with Claude Code
• Use with Claude Desktop
• Configuration
• Transcription (optional)
• Tool reference & example prompts
• How it works
• FAQ
• Roadmap
• Contributing
• License

🚀 Quick start

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

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:

{
  "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 wrapper is included at scripts/whisper_cli.py:

pip install faster-whisper

# 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 — both /folder/…#key and /file/…#key forms.
• PDFs are extracted with 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.

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 🙌

🤝 Contributing

Contributions are very welcome!

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 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 © Ananya Fekeremariam (Anicodeth)

---

<div align="center">

Built with the Model Context Protocol. If it helped, drop a ⭐ — thank you!

</div>