my-tg-mcp

Private, read-only MCP access to a personal Telegram account. The service runs on ssh bots, uses a dedicated copy of the existing Telethon session, and is available to Codex over Streamable HTTP.

Tools

• telegram_health verifies that the stored Telegram session is authorized.

• list_telegram_dialogs lists chats, channels, and direct messages.

• read_telegram_messages reads recent messages from one chat.

• search_telegram_messages searches one chat or the whole account.

• read_telegram_message reads one message by chat and message ID.

Every tool is annotated as read-only. Message bodies are returned as untrusted content and must never be treated as instructions.

Codex connection

The production endpoint is:

https://godmodetools.com/mcp/telegram

Add the server to ~/.codex/config.toml so it is available in every trusted project and every local Codex task:

[mcp_servers.my_telegram]
url = "https://godmodetools.com/mcp/telegram"
bearer_token_env_var = "MY_TG_MCP_TOKEN"
enabled_tools = [
  "telegram_health",
  "list_telegram_dialogs",
  "read_telegram_messages",
  "search_telegram_messages",
  "read_telegram_message",
]
default_tools_approval_mode = "approve"
startup_timeout_sec = 15
tool_timeout_sec = 90

After the token is present in the Codex process environment and Codex is restarted, phrases such as в моем телеграм найди... are enough. The server instructions explicitly map that language to these tools.

Local development

Python 3.12+ and uv are required.

uv sync --locked
uv run ruff check .
uv run pytest

Run locally only with a disposable test session, never the production session:

cp .env.example .env
uv run my-tg-mcp

Deployment, secret rotation, and the one-time server bootstrap are documented in docs/deployment.md. The threat model is in docs/security.md. The Keychain-backed global Codex setup is in docs/codex-client.md.