Telegram MCP Server

A security-first Model Context Protocol server for your personal Telegram account. Let Claude Code, Claude Desktop, Cursor or any MCP client read your chats, clean up spam groups, remove deleted-account chats and harden your privacy settings, using Telegram's official MTProto API via Telethon.

Every destructive action is dry-run by default: the assistant has to show you a preview and get your confirmation before anything is deleted, left or revoked.

Contents

• Why this server

• Tools

• Requirements

• Quick start

• Connect your MCP client

• Configuration

• Security model

• Example prompts

• Troubleshooting

• Development

• Disclaimer

Related MCP server: telegram-mcp

Why this server

Tools

Requirements

• Python 3.10+ and uv (recommended)

• A Telegram account

• Your own API credentials from my.telegram.org

Quick start

1. Get Telegram API credentials

1. Sign in at https://my.telegram.org and open API development tools.

2. Create an application (any name and platform).

3. Copy the App api_id and App api_hash.

api_hash is a secret. Do not share it and do not commit it.

2. Store the credentials

mkdir -p ~/.telegram-mcp
curl -fsSL https://raw.githubusercontent.com/lyduchuy1204/telegram-mcp-server/main/.env.example -o ~/.telegram-mcp/.env
chmod 600 ~/.telegram-mcp/.env      # macOS / Linux

Edit ~/.telegram-mcp/.env:

TELEGRAM_API_ID=1234567
TELEGRAM_API_HASH=your_32_character_api_hash

On Windows, create %USERPROFILE%\.telegram-mcp\.env with the same content.

3. Log in once

uvx --from git+https://github.com/lyduchuy1204/telegram-mcp-server telegram-mcp-login

Enter your phone number in international format (+14155550100), the code Telegram sends to your Telegram app, and your two-step verification password if you have one. The session is saved to ~/.telegram-mcp/telegram.session.

git clone https://github.com/lyduchuy1204/telegram-mcp-server.git
cd telegram-mcp-server
uv sync
uv run telegram-mcp-login

Then use uv --directory /absolute/path/to/telegram-mcp-server run telegram-mcp as the server command below.

Connect your MCP client

Claude Code

claude mcp add telegram -- uvx --from git+https://github.com/lyduchuy1204/telegram-mcp-server telegram-mcp

Run /mcp inside Claude Code to check that telegram shows connected.

Claude Desktop, Cursor, Windsurf and other clients

Add this to the client's MCP config (claude_desktop_config.json, ~/.cursor/mcp.json, and so on):

{
  "mcpServers": {
    "telegram": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/lyduchuy1204/telegram-mcp-server", "telegram-mcp"],
      "env": { "TELEGRAM_MCP_MODE": "safe" }
    }
  }
}

Credentials are read from ~/.telegram-mcp/.env, so they do not need to be in the client config.

Pin a release for reproducible installs: git+https://github.com/lyduchuy1204/telegram-mcp-server@v0.1.0

Configuration

Precedence: process environment, then TELEGRAM_MCP_ENV_FILE, then ./.env, then ~/.telegram-mcp/.env.

Security model

The session file is equivalent to your logged-in Telegram app. Anyone who copies it can read and send messages as you, without your password or 2FA.

What this project does to protect you:

• The session is stored outside project folders, by default in ~/.telegram-mcp/, with 0700/0600 permissions on macOS and Linux, so it is not accidentally committed or synced.

• .gitignore blocks .env, *.session, MCP client configs and image files.

• Least privilege: choose read-only or safe mode when you only need to read or organise.

• Two-step confirmation: destructive tools return a preview first. The MCP client also asks you to approve each tool call unless you have allow-listed it.

• Untrusted content: the model is told never to follow instructions found inside Telegram messages.

• No logging of message contents, no network calls other than Telegram's own servers.

What you should do:

1. Enable two-step verification in Telegram (Settings → Privacy and Security).

2. Never paste your login code or session file into chats, issues or AI prompts.

3. Review Settings → Devices regularly. The MCP session shows up there and can be terminated at any time.

4. Do not run two server processes against the same session at once (Telegram may revoke it).

5. Revoke access quickly if a device is lost: terminate the session and delete ~/.telegram-mcp/telegram.session.

See SECURITY.md for reporting vulnerabilities.

Example prompts

• "List my archived chats and tell me which ones look like spam."

• "Find chats with deleted accounts and remove them." The assistant previews first, then asks you.

• "Leave every 18+ or scam group I'm in, but keep anything work-related."

• "Who can add me to groups? Change it to contacts only."

• "Which websites did I log into with Telegram? Revoke the ones I haven't used this year."

• "Summarise unread messages in the AWS group from today."

Troubleshooting

Development

git clone https://github.com/lyduchuy1204/telegram-mcp-server.git
cd telegram-mcp-server
uv sync
uv run pytest          # unit tests, no Telegram account needed
uv run ruff check .    # lint and security rules (bandit)

Project layout:

src/telegram_mcp/
  config.py        settings, .env loading, session file permissions
  app.py           MCP server, Telegram client, permission-mode tool registration
  helpers.py       pure converters (chats, messages, privacy rules, phone numbers)
  login.py         interactive login CLI
  server.py        entry point
  tools/
    chats.py       read, search, send, mark read, archive
    cleanup.py     delete, clear, leave and block (dry-run by default)
    account.py     profile, photo, privacy and web logins

Contributions are welcome. Please open an issue first for larger changes.

Disclaimer

This is an unofficial project and is not affiliated with Telegram. Automating a user account is subject to the Telegram API Terms of Service. Use it on your own account, at a human pace, and never for spam or bulk messaging.

License

MIT