Telegram MCP — local read-only access for AI agents

The local MCP server gives Codex, Claude, and other MCP clients three tools:

The server is read-only. There are no tools for sending, editing, or deleting messages in the code. The server runs locally via STDIO and intentionally does not provide network HTTP/SSE access.

Supported clients

• ChatGPT/Codex Desktop;

• Codex CLI and IDE extension;

• Claude Code;

• Claude Desktop;

• any local MCP client with STDIO support.

The local server does not work directly in chatgpt.com, claude.ai, on a phone, or on another computer: these environments cannot run a process on your machine.

Related MCP server: tdl-mcp

What you'll need

• Windows 10/11, macOS, or Linux;

• Git;

• Python 3.10+;

• at least one supported MCP client.

Installation for beginners

1. Open a terminal

• macOS: Command + Space → type Terminal → Enter.

• Windows: Start menu → type PowerShell → open PowerShell.

• Linux: press Ctrl + Alt + T or open the Terminal app.

2. Download the project

macOS/Linux:

git clone https://github.com/iamalexzatcepin/telegram-mcp-template.git ~/telegram-mcp
cd ~/telegram-mcp

Windows PowerShell:

git clone https://github.com/iamalexzatcepin/telegram-mcp-template.git "$env:USERPROFILE\telegram-mcp"
cd "$env:USERPROFILE\telegram-mcp"

If GitHub reports that the repository is not found, your account does not yet have access to the private repository.

3. Get your Telegram API ID and API Hash

1. Open my.telegram.org.

2. Sign in with your phone number.

3. Open API development tools.

4. Create an app, e.g. Local Telegram MCP.

5. Save api_id and api_hash.

Do not send api_hash, the login code, or the cloud password to an AI chat.

Create a local .env.

macOS/Linux:

cp .env.example .env
nano .env

Saving in Nano: Ctrl + O → Enter → Ctrl + X.

Windows PowerShell:

Copy-Item .env.example .env
notepad .env

Fill in the file locally:

TELEGRAM_API_ID=ваш_api_id
TELEGRAM_API_HASH=ваш_api_hash

4. Install dependencies and sign in to Telegram

macOS/Linux:

bash setup.sh

Windows PowerShell:

powershell -ExecutionPolicy Bypass -File setup.ps1

The script will find Python 3.10+ itself, create .venv, install dependencies, and ask for your phone number, the code from Telegram, and, if enabled, the cloud password. Enter them only in your own terminal.

Connecting to an agent

In all examples, use the absolute paths printed by the setup script. The command is Python inside .venv, the argument is telegram_mcp_server.py.

Codex CLI and ChatGPT/Codex Desktop

macOS/Linux:

codex mcp add telegram -- "$HOME/telegram-mcp/.venv/bin/python" "$HOME/telegram-mcp/telegram_mcp_server.py"
codex mcp get telegram

Windows PowerShell:

codex mcp add telegram -- "$env:USERPROFILE\telegram-mcp\.venv\Scripts\python.exe" "$env:USERPROFILE\telegram-mcp\telegram_mcp_server.py"
codex mcp get telegram

In ChatGPT/Codex Desktop you can also open Settings → MCP servers → Add server, select STDIO, and specify the same Command and Arguments. After saving, click Restart. Local clients of the same Codex host share the ~/.codex/config.toml configuration.

Claude Code

macOS/Linux:

claude mcp add --transport stdio --scope user telegram -- "$HOME/telegram-mcp/.venv/bin/python" "$HOME/telegram-mcp/telegram_mcp_server.py"
claude mcp get telegram

Windows PowerShell:

claude mcp add --transport stdio --scope user telegram -- "$env:USERPROFILE\telegram-mcp\.venv\Scripts\python.exe" "$env:USERPROFILE\telegram-mcp\telegram_mcp_server.py"
claude mcp get telegram

Start a new Claude Code session and type /mcp. The user scope makes the server available across different local projects of this user.

Claude Desktop

Open the Developer/MCP settings and add a local STDIO server. If your Claude Desktop version uses a JSON configuration, add the object while keeping the other servers:

{
  "mcpServers": {
    "telegram": {
      "command": "/absolute/path/to/telegram-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/telegram-mcp/telegram_mcp_server.py"]
    }
  }
}

Typical file locations:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json;

• Windows: %APPDATA%\Claude\claude_desktop_config.json.

Fully restart Claude Desktop and open a new chat.

Another STDIO MCP client

Use an equivalent configuration:

{
  "mcpServers": {
    "telegram": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["/absolute/path/to/telegram_mcp_server.py"]
    }
  }
}

Final check

Ask the agent:

Use telegram list_chats with limit=10 and show the name, type, and number of unread messages.

Do not consider the installation complete until the agent has actually returned the list of your chats.

Multiple accounts

The server supports separate local sessions default, work, personal, and others. Instructions are in docs/MULTI_ACCOUNT.md.

Instructions for AI agents

If Codex, Claude, or another agent is performing the installation, ask it to fully read docs/AGENT_SETUP.md and follow it step by step. This file contains security rules and branches for different OSes.

Security and limitations

• .env and sessions/ are excluded from Git;

• the .session file grants access to the account — do not copy or publish it;

• media files are not downloaded, only the has_media flag is returned;

• requests to Telegram are executed on behalf of your account and obey Telegram's limits;

• do not run two operations with the same .session at the same time;

• do not expose this server to the internet.

More: SECURITY.md.

If something doesn't work

See docs/TROUBLESHOOTING.md.

Development

.venv/bin/python -m unittest discover -s tests -v

Project structure:

License

MIT — the project can be used, modified, and distributed with the copyright notice and the license text preserved.