telegram-desktop-mcp 0.1.0__tar.gz

telegram_desktop_mcp-0.1.0/.env.example

@@ -0,0 +1,3 @@
+TELEGRAM_API_ID=123456
+TELEGRAM_API_HASH=your_api_hash_here
+TELEGRAM_SESSION=telegram_mcp

telegram_desktop_mcp-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,35 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch: # يتيح لك تشغيل النشر يدوياً بضغطة زر من تبويب Actions
+
+jobs:
+  pypi-publish:
+    name: Upload release to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/${{ github.event.repository.name }}
+    permissions:
+      id-token: write # إلزامي للمصادقة الموثوقة مع PyPI بدون كلمات سر
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

telegram_desktop_mcp-0.1.0/.github/workflows/python-publish.yml

@@ -0,0 +1,70 @@
+# This workflow will upload a Python Package to PyPI when a release is created
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python#publishing-to-package-registries
+
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+name: Upload Python Package
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  release-build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Build release distributions
+        run: |
+          # NOTE: put your own distribution build steps here.
+          python -m pip install build
+          python -m build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+  pypi-publish:
+    runs-on: ubuntu-latest
+    needs:
+      - release-build
+    permissions:
+      # IMPORTANT: this permission is mandatory for trusted publishing
+      id-token: write
+
+    # Dedicated environments with protections for publishing are strongly recommended.
+    # For more information, see: https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment#deployment-protection-rules
+    environment:
+      name: pypi
+      # OPTIONAL: uncomment and update to include your PyPI project URL in the deployment status:
+      # url: https://pypi.org/p/YOURPROJECT
+      #
+      # ALTERNATIVE: if your GitHub Release name is the PyPI project version string
+      # ALTERNATIVE: exactly, uncomment the following line instead:
+      # url: https://pypi.org/project/YOURPROJECT/${{ github.event.release.name }}
+
+    steps:
+      - name: Retrieve release distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+      - name: Publish release distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

telegram_desktop_mcp-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.env
+*.session
+*.session-journal
+__pycache__/
+.venv/
+venv/

telegram_desktop_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.5
+Name: telegram-desktop-mcp
+Version: 0.1.0
+Summary: A Telegram MCP server to control Telegram and read PDFs
+Requires-Python: >=3.10
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: pypdf>=4.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: qrcode>=7.4.0
+Requires-Dist: telethon>=1.36.0
+Description-Content-Type: text/markdown
+
+# Telegram MCP Server
+
+Telegram MCP server scaffold that logs in to Telegram using a QR code before starting the MCP server.
+
+This project uses:
+
+- `telethon` to connect to Telegram
+- `qrcode` to print a login QR code in the terminal
+- `python-dotenv` to load private keys from a local `.env` file
+
+> مهم: لا ترفع مفاتيح Telegram الخاصة بك أو ملف `.session` إلى GitHub.
+
+## Requirements
+
+- Python 3.10+
+- Telegram account
+- Telegram API credentials from <https://my.telegram.org>
+
+## 1. Get Telegram API ID and API Hash
+
+1. Open <https://my.telegram.org>
+2. Login with your Telegram phone number
+3. Go to **API development tools**
+4. Create an app
+5. Copy:
+   - `api_id`
+   - `api_hash`
+
+## 2. Install dependencies
+
+Create and activate a virtual environment:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+```
+
+Install packages:
+
+```bash
+pip install telethon qrcode python-dotenv
+```
+
+## 3. Configure environment variables
+
+Copy the example file:
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env`:
+
+```env
+TELEGRAM_API_ID=123456
+TELEGRAM_API_HASH=your_api_hash_here
+TELEGRAM_SESSION=telegram_mcp
+```
+
+Replace the values with your real Telegram credentials.
+
+## 4. How QR login works
+
+When the server starts, it checks if your Telegram session is already authorized.
+
+- If authorized, it continues normally.
+- If not authorized, it prints a QR code in the terminal.
+
+To login:
+
+1. Open Telegram on your phone
+2. Go to **Settings**
+3. Go to **Devices**
+4. Tap **Link Desktop Device**
+5. Scan the QR code from the terminal
+
+After scanning, a `.session` file is created locally. This file keeps you logged in.
+
+## 5. Run
+
+Current `server.py` contains the login helper and Telegram client setup.
+
+If your MCP server has a main function, call this before starting MCP:
+
+```python
+await before_mcp_start()
+```
+
+Example:
+
+```python
+async def main():
+    await before_mcp_start()
+    await mcp.run_async()
+```
+
+Then run:
+
+```bash
+python server.py
+```
+
+## Project files
+
+```text
+server.py       # Telegram client and QR login helper
+.env.example   # Example environment variables
+.gitignore     # Prevents secrets/session files from being committed
+README.md      # Documentation
+```
+
+## Security notes
+
+Do not commit or share these files:
+
+- `.env`
+- `*.session`
+- `*.session-journal`
+
+These files are ignored by `.gitignore`.
+
+If you accidentally publish your API hash or session file, revoke/regenerate credentials from Telegram and delete the leaked session.
+
+## Troubleshooting
+
+### `Please set TELEGRAM_API_ID and TELEGRAM_API_HASH`
+
+Make sure `.env` exists and contains valid values:
+
+```env
+TELEGRAM_API_ID=your_id
+TELEGRAM_API_HASH=your_hash
+```
+
+### QR code does not appear correctly
+
+Make sure your terminal supports ASCII output and is wide enough. Try zooming out or using a larger terminal window.
+
+### Login asks again every time
+
+Make sure the `.session` file is not being deleted. The session name comes from:
+
+```env
+TELEGRAM_SESSION=telegram_mcp
+```
+
+This creates a local file like:
+
+```text
+telegram_mcp.session
+```
+
+## Arabic quick start
+
+1. ثبت المكتبات:
+
+```bash
+pip install telethon qrcode python-dotenv
+```
+
+2. انسخ ملف البيئة:
+
+```bash
+cp .env.example .env
+```
+
+3. ضع مفاتيحك داخل `.env`.
+
+4. شغل السكربت:
+
+```bash
+python server.py
+```
+
+5. امسح QR من تطبيق تيليجرام.
+# Telegram-mcp

telegram_desktop_mcp-0.1.0/README.md

@@ -0,0 +1,176 @@
+# Telegram MCP Server
+
+Telegram MCP server scaffold that logs in to Telegram using a QR code before starting the MCP server.
+
+This project uses:
+
+- `telethon` to connect to Telegram
+- `qrcode` to print a login QR code in the terminal
+- `python-dotenv` to load private keys from a local `.env` file
+
+> مهم: لا ترفع مفاتيح Telegram الخاصة بك أو ملف `.session` إلى GitHub.
+
+## Requirements
+
+- Python 3.10+
+- Telegram account
+- Telegram API credentials from <https://my.telegram.org>
+
+## 1. Get Telegram API ID and API Hash
+
+1. Open <https://my.telegram.org>
+2. Login with your Telegram phone number
+3. Go to **API development tools**
+4. Create an app
+5. Copy:
+   - `api_id`
+   - `api_hash`
+
+## 2. Install dependencies
+
+Create and activate a virtual environment:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+```
+
+Install packages:
+
+```bash
+pip install telethon qrcode python-dotenv
+```
+
+## 3. Configure environment variables
+
+Copy the example file:
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env`:
+
+```env
+TELEGRAM_API_ID=123456
+TELEGRAM_API_HASH=your_api_hash_here
+TELEGRAM_SESSION=telegram_mcp
+```
+
+Replace the values with your real Telegram credentials.
+
+## 4. How QR login works
+
+When the server starts, it checks if your Telegram session is already authorized.
+
+- If authorized, it continues normally.
+- If not authorized, it prints a QR code in the terminal.
+
+To login:
+
+1. Open Telegram on your phone
+2. Go to **Settings**
+3. Go to **Devices**
+4. Tap **Link Desktop Device**
+5. Scan the QR code from the terminal
+
+After scanning, a `.session` file is created locally. This file keeps you logged in.
+
+## 5. Run
+
+Current `server.py` contains the login helper and Telegram client setup.
+
+If your MCP server has a main function, call this before starting MCP:
+
+```python
+await before_mcp_start()
+```
+
+Example:
+
+```python
+async def main():
+    await before_mcp_start()
+    await mcp.run_async()
+```
+
+Then run:
+
+```bash
+python server.py
+```
+
+## Project files
+
+```text
+server.py       # Telegram client and QR login helper
+.env.example   # Example environment variables
+.gitignore     # Prevents secrets/session files from being committed
+README.md      # Documentation
+```
+
+## Security notes
+
+Do not commit or share these files:
+
+- `.env`
+- `*.session`
+- `*.session-journal`
+
+These files are ignored by `.gitignore`.
+
+If you accidentally publish your API hash or session file, revoke/regenerate credentials from Telegram and delete the leaked session.
+
+## Troubleshooting
+
+### `Please set TELEGRAM_API_ID and TELEGRAM_API_HASH`
+
+Make sure `.env` exists and contains valid values:
+
+```env
+TELEGRAM_API_ID=your_id
+TELEGRAM_API_HASH=your_hash
+```
+
+### QR code does not appear correctly
+
+Make sure your terminal supports ASCII output and is wide enough. Try zooming out or using a larger terminal window.
+
+### Login asks again every time
+
+Make sure the `.session` file is not being deleted. The session name comes from:
+
+```env
+TELEGRAM_SESSION=telegram_mcp
+```
+
+This creates a local file like:
+
+```text
+telegram_mcp.session
+```
+
+## Arabic quick start
+
+1. ثبت المكتبات:
+
+```bash
+pip install telethon qrcode python-dotenv
+```
+
+2. انسخ ملف البيئة:
+
+```bash
+cp .env.example .env
+```
+
+3. ضع مفاتيحك داخل `.env`.
+
+4. شغل السكربت:
+
+```bash
+python server.py
+```
+
+5. امسح QR من تطبيق تيليجرام.
+# Telegram-mcp

telegram_desktop_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "telegram-desktop-mcp"  # نفس الاسم الذي وضعته في PyPI
+version = "0.1.0"
+description = "A Telegram MCP server to control Telegram and read PDFs"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "mcp>=1.0.0",
+    "telethon>=1.36.0",
+    "pypdf>=4.0.0",
+    "qrcode>=7.4.0",
+    "python-dotenv>=1.0.0",
+]
+
+[project.scripts]
+telegram-mcp = "server:main"
+
+[tool.hatch.build.targets.wheel]
+only-include = ["server.py"]

telegram_desktop_mcp-0.1.0/requirements.txt

@@ -0,0 +1,37 @@
+annotated-types==0.8.0
+anyio==4.15.1
+arabic-reshaper==3.0.1
+attrs==26.1.0
+cffi==2.1.1
+click==8.5.0
+cryptography==50.0.1
+h11==0.16.0
+httpcore2==2.13.1
+httpx2==2.13.1
+idna==3.20
+jsonschema==4.26.0
+jsonschema-specifications==2025.9.1
+mcp==2.2.0
+mcp-types==2.2.0
+opentelemetry-api==1.45.0
+pyaes==1.6.1
+pyasn1==0.6.4
+pycparser==3.0
+pydantic==2.13.5
+pydantic_core==2.46.5
+PyJWT==2.15.0
+pypdf==6.19.0
+python-bidi==0.6.11
+python-dotenv==1.2.3
+python-multipart==0.0.32
+qrcode==8.2
+referencing==0.37.0
+rpds-py==2026.6.3
+rsa==4.9.1
+sse-starlette==3.4.11
+starlette==1.7.0
+Telethon==1.45.0
+truststore==0.10.4
+typing_extensions==4.16.0
+typing-inspection==0.4.4
+uvicorn==0.54.0

telegram_desktop_mcp-0.1.0/server.py

@@ -0,0 +1,75 @@
+import os
+import sys
+
+import qrcode
+from dotenv import load_dotenv
+from telethon import TelegramClient
+
+try:
+    import arabic_reshaper
+    from bidi.algorithm import get_display
+except ImportError:  # Optional terminal-only display helpers.
+    arabic_reshaper = None
+    get_display = None
+
+load_dotenv()
+
+API_ID = int(os.getenv("TELEGRAM_API_ID", "0"))
+API_HASH = os.getenv("TELEGRAM_API_HASH", "")
+SESSION_NAME = os.getenv("TELEGRAM_SESSION", "telegram_mcp")
+
+
+if not API_ID or not API_HASH:
+    raise RuntimeError(
+        "Please set TELEGRAM_API_ID and TELEGRAM_API_HASH in environment variables or a .env file."
+    )
+
+
+client = TelegramClient(SESSION_NAME, API_ID, API_HASH)
+
+
+if hasattr(sys.stdout, "reconfigure"):
+    sys.stdout.reconfigure(encoding="utf-8")
+
+
+def terminal_arabic(text: str) -> str:
+    """Shape Arabic so it displays correctly in LTR terminals and agent output."""
+    if arabic_reshaper and get_display:
+        return get_display(arabic_reshaper.reshape(text))
+    return text
+
+
+def print_arabic(text: str = "") -> None:
+    print(terminal_arabic(text))
+
+
+async def login_with_qr(client: TelegramClient):
+    """Log in to Telegram using a QR code before starting the MCP server."""
+    if not client.is_connected():
+        await client.connect()
+
+    if await client.is_user_authorized():
+        return
+
+    qr_login = await client.qr_login()
+    print()
+    print_arabic("--- امسح رمز QR التالي من تطبيق تيليجرام على هاتفك: ---")
+
+    qr = qrcode.QRCode()
+    qr.add_data(qr_login.url)
+    qr.print_ascii(invert=True)
+
+    await qr_login.wait()
+    print_arabic("تم تسجيل الدخول بنجاح!")
+    print()
+
+
+async def before_mcp_start():
+    """Call this before running the MCP server."""
+    await login_with_qr(client)
+
+
+# Example usage when you add/run your MCP server:
+# async def main():
+#     await before_mcp_start()
+#     await mcp.run_async()