How do I use telegram-mcp-server?

1. Click on "Install 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 Related Servers Score Discussions

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 installed

license - not found

Not graded

quality - not tested

maintenance

How are these scores calculated?

Maintenance

–Maintainers

–Response time

–Release cycle

–Releases (12mo)

Commit activity

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

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 a month ago (2026-07-23 20:34 UTC)
1
tdlib-mcp-server
Communication Search
Crocodile-beep
F
license
Not graded
quality
C
maintenance
Connects AI agents to Telegram via the official TDLib library, enabling tools like getting user info, listing dialogs, and searching messages.
Updated 2 months ago (2026-06-08 16:35 UTC)
telegram-mcp
Communication
chenzhaoxuan0
A
license
Not graded
quality
C
maintenance
Enables interaction with Telegram Bot API for sending messages, photos, editing messages, answering callbacks, and fetching updates.
Updated 2 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 4 months ago (2026-04-08 19:58 UTC)
58
1
MIT

View all related MCP servers

Related MCP Connectors

fast-mcp-telegram
Multi-tenant Telegram gateway for AI agents — HTTP+stdio, 8 tools, MTProto User API
telegram-mcp
Telegram bridge for your MCP-compatible agent. Bidirectional, no LLM in our stack.
tgden — Telegram catalog & search
Search 1.2M+ Telegram channels, 245k+ chats, 160k+ bots — no account, no key, no install.

View all MCP Connectors

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Steph-ux/telegram-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

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

Looking for Admin?

Related MCP Servers

Telegram MCP Server

tdlib-mcp-server

telegram-mcp

Telegram Bot MCP Server

Related MCP Connectors

Latest Blog Posts

MCP directory API

`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