A powerful, self-hosted Telegram Stremio Media Server built with FastAPI, MongoDB, and PyroFork — seamlessly integrated with Stremio for automated media streaming and discovery.
This project is a next-generation Telegram Stremio Media Server that allows you to stream your Telegram files directly through Stremio, without any third-party dependencies or file expiration issues. It’s designed for speed, scalability, and reliability, making it ideal for both personal and community-based media hosting.
- ⚙️ Multiple MongoDB Database Support
- 📡 Multiple Telegram Channel Support
- ⚡ Ultra-Fast Streaming Experience
- 🔑 Multi-Token Load Balancer
- 🎬 IMDb & TMDb Metadata Integration
- 🧩 Seamless Split File Streaming Support
- 🎞️ Play Multi-Part Videos as a Single Stream
- ♾️ Permanent Streaming Links (No Expiration)
- 🧠 Powerful Admin Dashboard
- 💳 Subscription & Premium Management
- 🔐 Advanced Access Control System
- 📚 Custom & Automatic Catalog Generation
- 🖥️ Web-Based Configuration Panel
- 🌐 Built-in Addon Proxy Support
- 🔍 Global Search Across Selected Channels
This project acts as a bridge between Telegram storage and Stremio streaming, connecting Telegram, FastAPI, and Stremio to enable seamless movie and TV show streaming directly from Telegram files.
When you forward Telegram files (movies or TV episodes) to your AUTH CHANNEL, the bot automatically:
- 🗃️ Stores the
message_idandchat_idin the database. - 🧠 Processes file captions to extract key metadata (title, year, quality, etc.).
- 🌐 Generates a streaming URL through the PyroFork module — routed by FastAPI.
- 🎞️ Provides Stremio Addon APIs:
/catalog→ Lists available media/meta→ Shows detailed information for each item/stream→ Streams the file directly via Telegram
To ensure proper metadata extraction and seamless integration with Stremio, all uploaded Telegram media files must include specific details in their captions.
Example Caption:
Ghosted 2023 720p 10bit WEBRip [Org APTV Hindi AAC 2.0CH + English 6CH] x265 HEVC Msub ~ PSA.mkv
Required Fields:
- 🎞️ Name – Movie title (e.g., Ghosted)
- 📅 Year – Release year (e.g., 2023)
- 📺 Quality – Resolution or quality (e.g., 720p, 1080p, 2160p)
✅ Optional: Include codec, audio format, or source (e.g., WEBRip, x265, Dual Audio).
Example Caption:
Harikatha.Sambhavami.Yuge.Yuge.S01E04.Dark.Hours.1080p.WEB-DL.DUAL.DDP5.1.Atmos.H.264-Spidey.mkv
Required Fields:
- 🎞️ Name – TV show title (e.g., Harikatha Sambhavami Yuge Yuge)
- 📆 Season Number – Use
Sfollowed by two digits (e.g.,S01) - 🎬 Episode Number – Use
Efollowed by two digits (e.g.,E04) - 📺 Quality – Resolution or quality (e.g., 1080p, 720p)
✅ Optional: Include episode title, codec, or audio details (e.g., WEB-DL, DDP5.1, Dual Audio).
Works only when Replace Mode is enabled.
If a newly uploaded file has the same quality label (720p, 1080p, 4K, etc.) as an existing file, the bot automatically replaces the older entry with the new one.
Example: Uploading a new Ghosted (2023) 720p file will replace the existing 720p version in the catalog.
This prevents duplicate quality entries and ensures only the latest version is available for streaming.
Works only when Replace Mode is enabled.
If you initially uploaded a CAMRip or low-quality version, you can easily replace it with a better one:
- Forward the new, higher-quality file (e.g.,
1080p,WEB-DL) to your AUTH CHANNEL. - The bot will automatically detect and replace the old CAMRip file in the database.
- The Stremio addon will then update automatically, showing the new stream source.
✅ No manual deletion or command is needed — forwarding the updated file is enough!
If the addon identifies a movie or TV show incorrectly, or if metadata is missing altogether, you can easily correct it using one of the following methods:
-
Copy the correct IMDb or TMDb URL for the movie or TV show.
-
Edit the message caption in your Telegram AUTH CHANNEL and paste the URL anywhere in the caption.
-
The bot will automatically:
- Remove the existing metadata entry associated with that file.
- Re-scan the provided URL.
- Fetch and save the correct metadata.
- Open the media entry from the Movies or TV Shows section.
- Click Edit.
- Select Scan Metadata.
- Search for the correct title and choose the matching result.
- Apply the changes.
✅ The addon will update the metadata instantly and refresh the catalog entry.
Here's how each component interacts:
| Component | Role |
|---|---|
| Telegram Bot | Handles uploads, forwards, and file tracking. |
| MongoDB | Stores message IDs, chat IDs, and metadata. |
| PyroFork | Generates Telegram-based streaming URLs. |
| FastAPI | Hosts REST endpoints for streaming, catalog, and metadata. |
| Stremio Addon | Consumes FastAPI endpoints for catalog display and playback. |
📦 Flow Summary:
Telegram ➜ MongoDB ➜ FastAPI ➜ Stremio ➜ User Stream
Below is the list of available bot commands and their usage within the Telegram bot.
| Command | Description |
|---|---|
/start |
Returns your Addon URL for direct installation in Stremio. |
/log |
Sends the latest log file for debugging or monitoring. |
/set |
Used for manual uploads by linking IMDB URLs. |
/restart |
Restarts the bot and pulls any latest updates from the upstream repository. |
The /set command is used to manually upload a specific Movie or TV show to your channel, linking it to its IMDB metadata.
Command:
/set <imdb-url>
Example:
/set https://www.imdb.com/title/tt0468569/
Steps:
- Send the
/setcommand followed by the IMDB URL of the movie or show you want to upload. - Forward the related movie or TV show files to your channel.
- Once all files are uploaded, clear the default IMDB link by simply sending the
/setcommand without any URL.
💡 Tip: Use /log if you encounter any upload or parsing issues.
😌 Don’t worry — setup is easier than it looks. You only fill in 6 values once inside a single file called
config.env. Everything else (TMDB key, channels, admin login, subscriptions, proxy…) is configured later from a friendly Web Settings page — no code, no restarts.
Think of configuration as two simple layers:
| Layer | Where | When you set it | What goes here |
|---|---|---|---|
| 🧱 Startup | config.env file |
Once, before first launch | The core credentials needed to boot |
| 🎛️ Runtime | Web Settings page | Anytime, after launch | Everything else — saved to the database, applied live |
After cloning the project, copy the sample file and open it for editing:
cp sample_config.env config.env
nano config.envFill in these values:
| Variable | Required | What it is |
|---|---|---|
API_ID |
✅ | Telegram API ID (from my.telegram.org) |
API_HASH |
✅ | Telegram API Hash (from my.telegram.org) |
BOT_TOKEN |
✅ | Your bot token (from @BotFather) |
OWNER_ID |
✅ | Your numeric Telegram user ID |
DATABASE |
✅ | Two MongoDB URIs, separated by a comma |
PORT |
✅ | Web server port (keep 8000 unless it’s busy) |
USER_SESSION_STRING |
⬜ | Optional — only needed for Global Search |
A completed file looks like this (these are just example values):
API_ID="1234567"
API_HASH="abc123def456ghi789jkl012mno345pq"
BOT_TOKEN="1234567890:AAEabcdEFGhijkLMnOPqrsTUVwxyz12345"
USER_SESSION_STRING=""
OWNER_ID="987654321"
DATABASE="mongodb+srv://user:pass@cluster0.xxxx.mongodb.net/tracking,mongodb+srv://user:pass@cluster0.xxxx.mongodb.net/storage1"
PORT="8000"💾 To save in nano: press
Ctrl + O, thenEnter, thenCtrl + X.
Take it one line at a time — each value comes from a quick, free step.
- Go to https://my.telegram.org and log in with your phone number.
- Open API development tools.
- Create an app (any title works, e.g.
stremio). - Copy App api_id →
API_IDand App api_hash →API_HASH.
- Open @BotFather in Telegram.
- Send
/newbotand follow the prompts (choose a name and a username). - Copy the token it gives you →
BOT_TOKEN. - ⭐ Add this bot as an admin in every channel you’ll use for media.
- Open @userinfobot in Telegram (or send
/idto @MissRose_bot). - It replies with your numeric ID →
OWNER_ID.
You need two free MongoDB databases — the first stores tracking/metadata, the second stores your media references.
- Create a free account at https://www.mongodb.com/atlas (the forever-free M0 tier is enough to start).
- Create a cluster → in Database Access, add a database user and password.
- In Network Access, add
0.0.0.0/0(allow access from anywhere). - Click Connect → Drivers and copy the connection string, e.g.
mongodb+srv://user:pass@cluster0.xxxx.mongodb.net/ - Add a database name at the end of each (e.g.
/trackingand/storage1). - Put both strings on one line, separated by a comma:
DATABASE="mongodb+srv://.../tracking,mongodb+srv://.../storage1"
💡 You can use the same cluster for both — just give them two different database names. Need more space later? Add extra storage databases from the Web Settings page (no restart required).
Leave it as 8000 unless that port is already in use. Your reverse proxy / domain will point here.
Only needed if you want Global Search. It’s safe and quick to generate — see Step 3 below. If you don’t need Global Search, leave it empty.
😊 No app installation required — and it’s safe. A session string is simply a “stay logged in” token for your own Telegram account, exactly like signing into Telegram Web. The bot never sees your password, and you can revoke access anytime from Telegram → Settings → Devices.
⏭️ Skip this step entirely if you don’t plan to use Global Search.
1️⃣ Open https://colab.new in your browser.
2️⃣ Sign in with your Google account.
3️⃣ Tap “+ Code” to add a new code cell.
4️⃣ Paste the code below and press ▶ Run:
!pip install pyrogram tgcrypto
import asyncio
from pyrogram import Client
api_id = int(input("API ID: "))
api_hash = input("API HASH: ")
async def main():
async with Client("temp_session", api_id, api_hash) as app:
print("\nYour USER_SESSION_STRING is:\n")
print(await app.export_session_string())
await main()5️⃣ Enter your API ID and API HASH when prompted.
6️⃣ Enter the login code Telegram sends you (and your 2-step password, if you have one).
7️⃣ Your USER_SESSION_STRING is printed on screen — copy the whole string into config.env.
🔒 Keep it private. Anyone who has this string can access your account, so never share it or commit it to a public repository. To invalidate it instantly, just remove the session from Telegram’s Devices list.
Once the server is running, open it in your browser:
| Setup | Open this URL |
|---|---|
| VPS with a domain | https://your-domain.com |
| Local / direct IP | http://<your-vps-ip>:8000 |
You’ll land on the login page (/login). Sign in with the default credentials:
Username: admin
Password: admin
Then go to Settings (/admin/settings).
🚨 Do this first: change the admin password in the Admin Authentication card, then click Save Settings.
Everything below is stored in the database and applied instantly — no restart needed (the only exception is USER_SESSION_STRING, which lives in config.env).
| Option | What it does |
|---|---|
| Replace Mode | When a new file has the same quality (720p, 1080p…) as an existing one, it replaces the old entry. Recommended ON. |
| Hide Catalog | Hides the public Stremio catalog (direct streams still work). |
| Field | What to enter |
|---|---|
| Admin Username / Password | Your Web Panel login. Leave the password blank to keep the current one. Change the defaults right away. |
| AUTH_CHANNELS | The channel(s) the bot indexes and streams from. Add each one by @username or -100… ID. Make sure your bot is an admin in each channel. |
| Field | What to enter |
|---|---|
| TMDB API Key | A free TMDB v3 key from themoviedb.org → Settings → API. Powers automatic metadata matching. |
| Base URL | Your public address, e.g. https://your-domain.com. Important: Stremio uses this to reach your streams. |
| Upstream Repo / Branch | Optional — used by /restart to auto-update (e.g. repo weebzone/Telegram-Stremio, branch master). |
Turn this on to monetise access. Set the Subscription Group ID, Payment Instructions (your UPI / bank / PayPal text), an optional Payment QR image URL, and the Approver IDs (who can approve requests). Renewal and "join the channel" prompts shown in Stremio point users back to your bot automatically — no separate URL to configure. The full flow is described in Subscription Management.
Requires USER_SESSION_STRING in config.env plus one app restart to unlock. Then enable the toggle and add the channel IDs to search. Results that aren’t in your local catalog are tagged 🌐 GLOBAL in Stremio.
Set an HTTP Proxy URL for outbound metadata/API requests, and optionally show both proxied and direct stream links.
Your first two databases (from config.env) are locked as Tracking and Storage 1. Add more MongoDB URIs here to expand storage capacity — 🟢 means connected. Remove entries only from the end of the list, since existing media reference databases by position.
Add extra bot tokens for faster parallel streaming under heavy load. Create more bots with @BotFather, add them as admins in all your AUTH channels, then paste their tokens here. Changes apply immediately.
✅ Click Save Settings when you’re done. That’s it — you’re live!
The Subscription Management system allows you to monetise access to your Telegram Stremio server. When enabled, users must have an active subscription to stream content.
Admins can create and manage subscription plans from the Admin Panel → Subscription Management page.
Each plan has:
- Name (e.g.
Monthly,Quarterly) - Duration in days
- Price (for display)
- Description
Plans are stored in MongoDB and can be added, edited, or deleted at any time without restarting.
Users interact with the bot to subscribe:
User → /start → selects plan → sends payment screenshot
→ Approver gets notification → Approve / Reject
→ On Approve:
✅ Subscription saved to DB
🔑 Stremio addon token auto-generated
📨 User receives Stremio install link + group invite
Approver actions (available to APPROVER_IDS):
| Button | Action |
|---|---|
| ✅ Approve | Activates subscription, generates addon token, invites user to group |
| ❌ Reject | Notifies user with rejection message |
The Admin Panel → Access Management page gives admins full control over all users and their addon tokens.
| Column | Description |
|---|---|
| Status | 🟢 Active / 🔴 Expired |
| User | Display name or User {id} |
| Addon Link | Stremio install URL + copy button |
| Created | Token creation date |
| Expires | Subscription expiry date |
| Actions | Buttons for managing the user |
| Button | Description |
|---|---|
| 📅 Assign | Assign or extend a subscription plan (adds days) |
| ➕ Extend | Add extra days to an active subscription |
| ➖ Reduce | Subtract days from an active subscription |
| 🚫 Revoke | Wipe subscription entirely (marks expired) |
| 🗑️ Del Token | Delete the addon token only (user still subscribed) |
| 🔗 Link User ID | Link an old/orphan token to a Telegram user ID to enable management |
💡 Manually created (old) tokens that have no linked user ID show a 🔗 Link User ID button. Once linked, all action buttons become available.
- 🔍 Search by user name or ID
- Filter by status: All / Active / Expired
- Pagination with configurable page size
Each user gets a unique addon token automatically generated on payment approval. Their Stremio addon URL is:
https://your-domain.com/stremio/{token}/manifest.json
The addon manifest updates dynamically per user:
| Scenario | Addon Name | Description |
|---|---|---|
| Active, has expiry | Telegram — Expires 28 Mar 2026 |
📅 Subscription active until 28 Mar 2026 |
| Active, no expiry | Telegram — Active |
✅ Subscription active |
| Default (no subscription mode) | Telegram |
Standard description |
The manifest version encodes the expiry date — when an admin extends or revokes a subscription, the version changes and Stremio detects an update.
When the subscription feature is enabled, the addon checks every stream request and shows a single actionable entry instead of the streams when the user isn't eligible. In both cases the stream link opens your bot (derived automatically from the bot's username — there is no URL to configure).
Plan expired — the user's subscription has lapsed:
{
"name": "🚫 Plan Expired",
"title": "Your plan is expired.\nRenew it from the bot to continue watching.",
"url": "https://t.me/your_bot"
}Not joined — the user is active but has left / never joined the subscription channel (the Subscription Group ID):
{
"name": "📢 Join Required",
"title": "First join the channel to stream it.\nTap here to open the bot and join.",
"url": "https://t.me/your_bot"
}Clicking the stream name opens the bot directly so the user can renew or rejoin. The membership check fails open — if Telegram is briefly unreachable or the bot can't read the group, legitimate users are never blocked.
Every addon has a Configure page at:
https://your-domain.com/stremio/{token}/configure
This page shows:
- User name, subscription status, expiry date
- ⚡ Install / Update in Stremio button (Stremio Web install flow)
- Manual install steps + 📋 Copy URL button
The ⚙️ gear icon in Stremio opens this page so users can reinstall after an admin updates their subscription.
This guide will help you deploy your Telegram Stremio Media Server using either Heroku or a VPS with Docker.
Supported Servers:
- 🟣 Heroku
- 🟢 VPS
Before you begin, ensure you have:
- ✅ A VPS with a public IP (e.g., Ubuntu on DigitalOcean, AWS, Vultr, etc.)
- ✅ A Domain name
Follow the instructions provided in the Google Colab Tool to deploy on Heroku.
This section explains how to deploy your Telegram Stremio Media Server on a VPS using Docker Compose (recommended) or Docker.
git clone https://github.com/weebzone/Telegram-Stremio
cd Telegram-Stremio
mv sample_config.env config.env
nano config.env- Fill in all required variables in
config.env. - Press
Ctrl + O, thenEnter, thenCtrl + Xto save and exit.
You can deploy the server using either Docker Compose (recommended) or plain Docker.
Docker Compose provides an easier and more maintainable setup, environment mounting, and restart policies.
docker compose up -dYour server will now be running at:
➡️ http://<your-vps-ip>:8000
If you need to modify environment values (like BASE_URL, AUTH_CHANNEL, etc.):
-
Edit the file:
nano config.env
-
Save your changes: (
Ctrl + O,Enter,Ctrl + X) -
Restart the container to apply updates:
docker compose restart
⚡ Since the config file is mounted, you don’t need to rebuild the image — changes apply automatically on restart.
If you prefer not to use Docker Compose, you can manually build and run the container.
docker build -t telegram-stremio .docker run -d -p 8000:8000 telegram-stremioYour server should now be running at:
➡️ http://<your-vps-ip>:8000
Go to your domain registrar and add an A record pointing to your VPS IP:
| Type | Name | Value |
|---|---|---|
| A | @ | 195.xxx.xxx.xxx |
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
chmod o+r /usr/share/keyrings/caddy-stable-archive-keyring.gpg
chmod o+r /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install caddy-
Edit the Caddyfile:
sudo nano /etc/caddy/Caddyfile
-
Replace contents with:
your-domain.com { reverse_proxy localhost:8000 }
- Replace
your-domain.comwith your actual domain name. - Adjust the port if you changed it in
config.env.
- Replace
-
Save and reload Caddy:
sudo systemctl reload caddy
✅ Your API will now be available securely at:
➡️ https://your-domain.com
Your media server works as a standard Stremio-style addon, so it plays in any compatible client. For the best compatibility and smoothest experience across devices, we recommend the Nuvio app — a free, open-source media hub for Android, Android TV, Fire TV, iOS, Windows, and TV that supports Stremio addon manifest URLs natively. (Content was rephrased for compliance with licensing restrictions.)
💡 Already using Stremio? It works too — just install the same addon URL below. Nuvio simply tends to handle these Telegram streams more reliably across more devices.
Download Nuvio from an official source:
| Platform | Source |
|---|---|
| Android / Android TV / Fire TV | Google Play |
| All platforms / latest builds | GitHub — tapframe/NuvioStreaming |
🔗 (Optional) Connect Trakt in the app to sync your watch history and progress across devices.
- Open Nuvio and go to the Addons section.
- Paste your addon manifest URL and install it:
| Deployment Method | Addon URL |
|---|---|
| Heroku | https://<your-heroku-app>.herokuapp.com/stremio/manifest.json |
| Custom Domain | https://<your-domain>/stremio/manifest.json |
- Done! 🎉 Your Telegram library now appears in the catalog and streams directly.
🔑 If you run in subscription mode, each user installs their own personal addon URL (
/stremio/{token}/manifest.json) that the bot gives them.
 |
 |
 |
 |
|---|---|---|---|
Karan |
Stremio |
ChatGPT |
VFlix Prime |
| Author | Stremio SDK | Refactor | Community Support |