mcp-server-telegram-pager 0.1.0__tar.gz

mcp_server_telegram_pager-0.1.0/.gitignore

@@ -0,0 +1,35 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual Environment
+.env
+.venv
+venv/
+ENV/
+
+# IDE
+.vscode/
+.idea/
+
+# Session Data
+*.session
+*.session-journal

mcp_server_telegram_pager-0.1.0/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: mcp-server-telegram-pager
+Version: 0.1.0
+Summary: A send-only Telegram Pager MCP server for personal AI notifications
+Requires-Python: >=3.10
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: telethon>=1.36.0
+Description-Content-Type: text/markdown
+
+# Telegram Pager MCP Server
+
+A specialized [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that allows AI coding assistants (like Cursor, Cline, or Claude Desktop) to send direct messages via your personal Telegram account.
+
+**Security First:** This server exposes exactly *one* tool (`send_telegram_message`). It is intentionally designed as a "Telegram Pager", meaning the AI cannot read your chat history, delete messages, or view your contacts.
+
+## Prerequisites
+
+To use this, you need a Telegram API ID and Hash.
+1. Log in to [my.telegram.org/apps](https://my.telegram.org/apps).
+2. Create an application (if you haven't already).
+3. Copy your `App api_id` and `App api_hash`.
+
+## Installation & Setup
+
+1. **Clone the repository and install dependencies:**
+   ```bash
+   git clone https://github.com/ashizam/mcp-server-telegram-pager.git
+   cd mcp-server-telegram-pager
+   pipx install .
+   ```
+
+2. **Generate your Session String:**
+   Because Telegram requires 2FA (a login code sent to your app), you must generate an authentication session string locally first.
+   ```bash
+   mcp-server-telegram-pager-auth
+   ```
+   *Follow the prompts to enter your API ID, Hash, and Login Code. Copy the long session string it outputs!*
+
+## Configuring your MCP Client
+
+Add the following to your IDE's MCP configuration file (e.g., in Cursor or Claude Desktop):
+
+```json
+{
+  "mcpServers": {
+    "telegram-pager": {
+      "command": "mcp-server-telegram-pager",
+      "env": {
+        "TELEGRAM_API_ID": "YOUR_API_ID_HERE",
+        "TELEGRAM_API_HASH": "YOUR_API_HASH_HERE",
+        "TELEGRAM_SESSION": "YOUR_LONG_SESSION_STRING_HERE"
+      }
+    }
+  }
+}
+```
+
+## How to Test
+Once configured, you can ask your AI assistant:
+> "Send a Telegram message to username 'coolperson123' saying 'The build finished successfully!'"
+
+*(Note: Do not include the `@` symbol in the username).*

mcp_server_telegram_pager-0.1.0/README.md

@@ -0,0 +1,53 @@
+# Telegram Pager MCP Server
+
+A specialized [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that allows AI coding assistants (like Cursor, Cline, or Claude Desktop) to send direct messages via your personal Telegram account.
+
+**Security First:** This server exposes exactly *one* tool (`send_telegram_message`). It is intentionally designed as a "Telegram Pager", meaning the AI cannot read your chat history, delete messages, or view your contacts.
+
+## Prerequisites
+
+To use this, you need a Telegram API ID and Hash.
+1. Log in to [my.telegram.org/apps](https://my.telegram.org/apps).
+2. Create an application (if you haven't already).
+3. Copy your `App api_id` and `App api_hash`.
+
+## Installation & Setup
+
+1. **Clone the repository and install dependencies:**
+   ```bash
+   git clone https://github.com/ashizam/mcp-server-telegram-pager.git
+   cd mcp-server-telegram-pager
+   pipx install .
+   ```
+
+2. **Generate your Session String:**
+   Because Telegram requires 2FA (a login code sent to your app), you must generate an authentication session string locally first.
+   ```bash
+   mcp-server-telegram-pager-auth
+   ```
+   *Follow the prompts to enter your API ID, Hash, and Login Code. Copy the long session string it outputs!*
+
+## Configuring your MCP Client
+
+Add the following to your IDE's MCP configuration file (e.g., in Cursor or Claude Desktop):
+
+```json
+{
+  "mcpServers": {
+    "telegram-pager": {
+      "command": "mcp-server-telegram-pager",
+      "env": {
+        "TELEGRAM_API_ID": "YOUR_API_ID_HERE",
+        "TELEGRAM_API_HASH": "YOUR_API_HASH_HERE",
+        "TELEGRAM_SESSION": "YOUR_LONG_SESSION_STRING_HERE"
+      }
+    }
+  }
+}
+```
+
+## How to Test
+Once configured, you can ask your AI assistant:
+> "Send a Telegram message to username 'coolperson123' saying 'The build finished successfully!'"
+
+*(Note: Do not include the `@` symbol in the username).*

mcp_server_telegram_pager-0.1.0/pyproject.toml

@@ -0,0 +1,18 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mcp-server-telegram-pager"
+version = "0.1.0"
+description = "A send-only Telegram Pager MCP server for personal AI notifications"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "mcp>=1.0.0",
+    "telethon>=1.36.0"
+]
+
+[project.scripts]
+mcp-server-telegram-pager = "mcp_server_telegram_pager.server:main"
+mcp-server-telegram-pager-auth = "mcp_server_telegram_pager.generate_session:main"

mcp_server_telegram_pager-0.1.0/src/mcp_server_telegram_pager/__init__.py

@@ -0,0 +1,4 @@
+# Export the FastMCP instance if needed elsewhere
+from .server import mcp
+
+__all__ = ["mcp"]

mcp_server_telegram_pager-0.1.0/src/mcp_server_telegram_pager/generate_session.py

@@ -0,0 +1,28 @@
+import asyncio
+from telethon.sync import TelegramClient
+from telethon.sessions import StringSession
+
+def main():
+    print("=======================================")
+    print(" Telegram Session Generator")
+    print("=======================================\n")
+    print("1. Go to https://my.telegram.org/apps and log in.")
+    print("2. Copy your App api_id and App api_hash.\n")
+
+    api_id = input("Enter your API_ID: ").strip()
+    api_hash = input("Enter your API_HASH: ").strip()
+
+    print("\nConnecting to Telegram... (You will receive a login code on your Telegram app)")
+
+    # Create an in-memory string session
+    with TelegramClient(StringSession(), int(api_id), api_hash) as client:
+        print("\n✅ Authentication Successful!")
+        print("\n=======================================")
+        print(" YOUR SESSION STRING (KEEP THIS SECRET)")
+        print("=======================================\n")
+        print(client.session.save())
+        print("\n=======================================")
+        print("Copy the long string above. You will need it for your MCP config.")
+
+if __name__ == "__main__":
+    main()

mcp_server_telegram_pager-0.1.0/src/mcp_server_telegram_pager/server.py

@@ -0,0 +1,47 @@
+import os
+import asyncio
+from mcp.server.fastmcp import FastMCP
+from telethon import TelegramClient
+from telethon.sessions import StringSession
+
+# Initialize the MCP server
+# This creates a server that exposes ONLY the tools defined below.
+mcp = FastMCP("Telegram Pager")
+
+@mcp.tool()
+async def send_telegram_message(username: str, message: str) -> str:
+    """
+    Send a direct message to a Telegram user.
+    Do not use the @ symbol in the username (e.g. use 'jakethesnake', not '@jakethesnake').
+    """
+    api_id = os.environ.get("TELEGRAM_API_ID")
+    api_hash = os.environ.get("TELEGRAM_API_HASH")
+    session_str = os.environ.get("TELEGRAM_SESSION")
+
+    if not all([api_id, api_hash, session_str]):
+        return "Error: TELEGRAM_API_ID, TELEGRAM_API_HASH, and TELEGRAM_SESSION environment variables must be set."
+
+    try:
+        # Connect using the pre-authenticated session string
+        client = TelegramClient(StringSession(session_str), int(api_id), api_hash)
+        await client.connect()
+
+        if not await client.is_user_authorized():
+            await client.disconnect()
+            return "Error: Session is invalid or expired. Please generate a new session string."
+
+        # Send the message (this is the ONLY capability the AI has access to)
+        await client.send_message(username, message)
+        await client.disconnect()
+        
+        return f"Successfully sent message to {username}."
+
+    except Exception as e:
+        return f"Failed to send message: {str(e)}"
+
+def main():
+    """Entry point for the package console script."""
+    mcp.run(transport="stdio")
+
+if __name__ == "__main__":
+    main()