# 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:

```text
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:

```toml
[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](https://docs.astral.sh/uv/) are required.

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

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

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

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