Merge pull request #124 from chigwell/123-resolve-unable-to-start-telegram-mcp-authentication

fix: improve error handling for unauthorized Telegram clients and update troubleshooting instructions

Author: chigwell

README.md

@@ -380,6 +380,10 @@ Telegram messages, display names, chat titles, and button labels are untrusted c
 ## Troubleshooting
 
 - **No Telegram session configured:** set `TELEGRAM_SESSION_STRING`, `TELEGRAM_SESSION_NAME`, or suffixed multi-account variants.
+- **Session is not authorized:** run `uv run session_string_generator.py` outside
+  the MCP server, use QR login when possible, then set `TELEGRAM_SESSION_STRING`
+  in `.env`. The MCP server does not perform interactive phone-code login over
+  stdio.
 - **Invalid API credentials:** verify `TELEGRAM_API_ID` and `TELEGRAM_API_HASH` at [my.telegram.org/apps](https://my.telegram.org/apps).
 - **Database is locked:** prefer string sessions, or make sure no other process is using the same file session.
 - **File tools are disabled:** pass allowed roots or configure MCP Roots in your client.

telegram_mcp/runner.py

@@ -11,11 +11,27 @@
 import telegram_mcp.tools  # noqa: F401 - registers MCP tools via decorators
 
 
+async def _connect_authorized_client(label, client) -> None:
+    await client.connect()
+    if await client.is_user_authorized():
+        return
+
+    raise RuntimeError(
+        f"Telegram client '{label}' is not authorized. Interactive phone login "
+        "is disabled for the MCP server because it runs over stdio. Generate a "
+        "session string with `uv run session_string_generator.py`, then set "
+        "TELEGRAM_SESSION_STRING or TELEGRAM_SESSION_STRING_<LABEL> in .env. "
+        "For existing file sessions, run the login outside the MCP server first."
+    )
+
+
 async def _main() -> None:
     try:
         labels = ", ".join(clients.keys())
         print(f"Starting {len(clients)} Telegram client(s) ({labels})...", file=sys.stderr)
-        await asyncio.gather(*(cl.start() for cl in clients.values()))
+        await asyncio.gather(
+            *(_connect_authorized_client(label, cl) for label, cl in clients.items())
+        )
 
         # Warm entity caches — StringSession has no persistent cache,
         # so fetch all dialogs once per client to populate them

tests/test_runner.py

@@ -0,0 +1,40 @@
+import pytest
+
+from telegram_mcp import runner
+
+
+class _FakeClient:
+    def __init__(self, *, authorized: bool):
+        self.authorized = authorized
+        self.connected = False
+        self.started = False
+
+    async def connect(self):
+        self.connected = True
+
+    async def is_user_authorized(self):
+        return self.authorized
+
+    async def start(self):
+        self.started = True
+
+
+@pytest.mark.asyncio
+async def test_connect_authorized_client_uses_existing_session_without_interactive_start():
+    client = _FakeClient(authorized=True)
+
+    await runner._connect_authorized_client("default", client)
+
+    assert client.connected is True
+    assert client.started is False
+
+
+@pytest.mark.asyncio
+async def test_connect_authorized_client_rejects_unauthorized_session():
+    client = _FakeClient(authorized=False)
+
+    with pytest.raises(RuntimeError, match="Interactive phone login is disabled"):
+        await runner._connect_authorized_client("default", client)
+
+    assert client.connected is True
+    assert client.started is False