How do I use telegram-mcp-server?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@telegram-mcp-server send a message to my boss saying I'll be 10 minutes late" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

de en es ja ko ru zh

telegram-mcp-server

by Steph-ux

Overview Schema Source Related Servers Discussions Admin

Python

Remote

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

Go to my.telegram.org
Log in with your phone number
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")

Related MCP server: tdlib-mcp-server

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

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

telegram C
com.jojapi
Telegram: FASTEST real time Telegram API. Retrieve channel's info and messages in milliseconds..
Communication Social Media
21
fast-mcp-telegram A
io.github.leshchenko1979
Multi-tenant Telegram gateway for AI agents — HTTP+stdio, 8 tools, MTProto User API
Communication
8249
Postlyra A
io.github.prof-1t
Manage Telegram drafts, media, schedules and publications from AI clients.
Social Media Communication
321
TeleBoostOAuth
app.teleboost
Telegram CRM: manage contacts, conversations, tickets, campaigns and analytics.
Communication CRM Customer Support
1

Related MCP Servers

Telegram MCP Server
Communication Social Media
shaxzodrashid
F
license
A
quality
B
maintenance
Enables AI agents to interact with Telegram via MTProto, supporting high-performance communication and seamless integration.
Updated 2 months ago (2026-07-23 20:34 UTC)
1
-
tdlib-mcp-server
Communication Search
Crocodile-beep
F
license
Not graded
quality
D
maintenance
Connects AI agents to Telegram via the official TDLib library, enabling tools like getting user info, listing dialogs, and searching messages.
Updated 3 months ago (2026-06-08 16:35 UTC)
-
telegram-mcp
Communication
chenzhaoxuan0
A
license
Not graded
quality
D
maintenance
Enables interaction with Telegram Bot API for sending messages, photos, editing messages, answering callbacks, and fetching updates.
Updated 3 months ago (2026-06-18 07:53 UTC)
MIT
Telegram Bot MCP Server
Communication App Automation
mattleads
A
license
Not graded
quality
B
maintenance
Enables sending Telegram messages, photos, and documents, and retrieving bot information through the Telegram Bot API.
Updated 5 months ago (2026-04-08 19:58 UTC)
23 npm
1
MIT

telegram-mcp-server

1. Install

Get your API credentials

One-time auth

2. Register in your MCP client

Claude Desktop / OpenCode

Docker

3. Tool catalog (9 tools, 8 actions)

tg_session — Session management

tg_message — Send, forward, delete, reply

tg_chat — Chat operations

tg_search — Search

tg_history — Chat history

tg_user — User operations

tg_media — Send media

tg_channel — Channel management

tg_draft — Draft messages

4. Environment variables

5. Safety

6. MCP resources

License

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Telegram MCP Server

tdlib-mcp-server

telegram-mcp

Telegram Bot MCP Server

`tg_session` — Session management

`tg_message` — Send, forward, delete, reply

`tg_chat` — Chat operations

`tg_search` — Search

`tg_history` — Chat history

`tg_user` — User operations

`tg_media` — Send media

`tg_channel` — Channel management

`tg_draft` — Draft messages