telegram-mcp-server

A Telegram MCP server via Telethon — persistent client, flood-safe, 9 grouped tools.

Zero API keys in code. Session files stored locally. Works with user accounts (2FA) and bots.

---

1. Install

git clone <this-repo> telegram-mcp-server
cd telegram-mcp-server

python -m venv .venv
# Windows:
.venv\Scripts\activate
# macOS/Linux:
source .venv/bin/activate

pip install -e .

Get your API credentials

1. Go to my.telegram.org
2. Log in with your phone number
3. Create an app → get API ID and API Hash

One-time auth

# User account (with 2FA support)
export TG_API_ID=12345
export TG_API_HASH="your_hash_here"
telegram-mcp-server --auth --phone +33612345678

# Or via MCP tool: tg_session(action="auth", api_id=12345, api_hash="...", phone="+33612345678")

---

2. Register in your MCP client

Claude Desktop / OpenCode

{
  "mcpServers": {
    "telegram": {
      "command": "telegram-mcp-server",
      "env": {
        "TG_API_ID": "12345",
        "TG_API_HASH": "your_hash_here"
      }
    }
  }
}

If not on PATH:

{
  "mcpServers": {
    "telegram": {
      "command": "/path/to/.venv/bin/python",
      "args": ["-m", "telegram_mcp_server"],
      "env": {
        "TG_API_ID": "12345",
        "TG_API_HASH": "your_hash_here"
      }
    }
  }
}

Docker

docker build -t telegram-mcp .
docker run -i --rm \
  -v ~/.telegram-mcp/sessions:/root/.telegram-mcp/sessions \
  -e TG_API_ID=12345 \
  -e TG_API_HASH="your_hash" \
  telegram-mcp

---

3. Tool catalog (9 tools, 8 actions)

tg_session — Session management

action	Required args	Description
auth	api_id, api_hash, phone or bot_token	Authenticate (2FA supported)
check	—	Check login status
logout	—	Delete session

tg_message — Send, forward, delete, reply

action	Required args	Description
send	target, text	Send a message
forward	target, message_id, to_target	Forward a message
delete	target, message_id	Delete a message
reply	target, message_id, text	Reply to a message

tg_chat — Chat operations

action	Required args	Description
list	—	List recent chats
info	target	Get chat info
members	target	List chat members
leave	target	Leave a chat

tg_search — Search

action	Required args	Description
messages	query	Search messages (optionally in target)
users	query	Search contacts/users
channels	query	Search channels

tg_history — Chat history

action	Required args	Description
messages	target	Get message history
media	target	Get media-only history
files	target	Get file-only history

tg_user — User operations

action	Required args	Description
me	—	Get your own info
info	target	Get user info
block	target	Block a user
unblock	target	Unblock a user

tg_media — Send media

action	Required args	Description
send_photo	target, file_path	Send a photo
send_video	target, file_path	Send a video
send_file	target, file_path	Send a document
send_voice	target, file_path	Send a voice note

tg_channel — Channel management

action	Required args	Description
create	title	Create a supergroup/channel
join	target	Join a channel
leave	target	Leave a channel
info	target	Get channel info

tg_draft — Draft messages

action	Required args	Description
save	target, text	Save a draft
list	—	List all drafts
delete	target	Delete a draft

---

4. Environment variables

Variable	Default	Description
TG_API_ID	0	Telegram API ID (from my.telegram.org)
TG_API_HASH	""	Telegram API Hash
TG_SESSION_DIR	~/.telegram-mcp/sessions	Session files location

---

5. Safety

• Rate limiter: Send actions capped at 5/min. Read actions unlimited.
• FloodWaitError auto-retry: Waits the required time (capped at 5 min).
• Session files: Local only, never committed to git.
• 2FA support: Full support for accounts with two-factor auth.

---

6. MCP resources

• tg://version — Server version
• tg://session/status — Login state

---

License

MIT