Telegram MCP Server

How to use

You interact with the Telegram MCP Server through an MCP client by configuring the MCP connection as either a local (stdio) server or a remote HTTP server. The server is designed to understand a broad set of Telegram actions, mapped to tools you call from your client. Begin by starting the server locally or in a container, then connect your MCP client using the recommended configuration. Use the provided tools to read chats, send messages, manage groups, and handle invitations or inline button callbacks. The design includes input validation for chat and user IDs and multiple fallbacks for critical tasks to improve reliability in real-world use.

How to install

Prerequisites: Python 3.10+, Telethon, MCP Python SDK, and an MCP client such as Claude Desktop or Cursor.

# 1. Clone the project
git clone https://github.com/chigwell/telegram-mcp.git
cd telegram-mcp

# 2. Install dependencies with uv
uv sync

# 3. Generate a session string
uv run session_string_generator.py

# 4. Configure environment variables
# Copy .env.example to .env and fill in your credentials
# TELEGRAM_API_ID=your_api_id_here
# TELEGRAM_API_HASH=your_api_hash_here
# TELEGRAM_SESSION_NAME=anon
# TELEGRAM_SESSION_STRING=your_session_string_here

Configuration for Claude & Cursor

You can configure the MCP connection directly in your Claude or Cursor configuration to point to the Telegram MCP Server. The example shows a complete stdio configuration that uses uv to run the server from a specified directory.

{
  "mcpServers": {
    "telegram-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/full/path/to/telegram-mcp",
        "run",
        "main.py"
      ]
    }
  }
}

Running with Docker

If you prefer containerized deployment, you can build and run the server with Docker. The process includes building the image and choosing either Docker Compose or a direct docker run invocation.

# 1. Build the image
docker build -t telegram-mcp:latest .

# Option A: Docker Compose (recommended for local use)
# 2A. Create a .env file in the project root with TELeGRAM_API_ID, TELEGRAM_API_HASH, and TELEGRAM_SESSION_STRING
# 3A. Run
docker compose up --build
# To run in the background
# docker compose up -d
# Stop with Ctrl+C
```

```bash
# Option B: Direct docker run
helm

Environment variables and file-based sessions

The server requires Telegram API credentials and a session string. You typically provide these through a .env file or environment variables when running in Docker. The common variables include TELEGRAM_API_ID, TELEGRAM_API_HASH, and TELEGRAM_SESSION_STRING or TELEGRAM_SESSION_NAME. The session string grants access to your Telegram account, so protect it accordingly.

Security considerations

Never expose your session string or API credentials. Treat the session string as a sensitive credential that grants full account access. All processing happens locally in the MCP client context; no data leaves your environment except requests to Telegram.

Troubleshooting

If you encounter issues, check the mcp_errors.log for detailed error messages, verify that your .env or environment variables are correctly set, and ensure the Telethon-based client has the necessary permissions for the requested actions. If a function requires a bot account, you will receive a clear notification.

get_chats

Fetch a paginated list of chats with optional paging parameters.

list_chats

List chats with metadata and optional filters.

get_chat

Retrieve detailed information about a specific chat.

create_group

Create a new group with a list of user IDs.

invite_to_group

Invite users to a group or channel.

create_channel

Create a channel or supergroup with a title and description.

edit_chat_title

Change the title of a chat, group, or channel.

delete_chat_photo

Remove the chat photo.

leave_chat

Leave a chat or channel.

get_participants

List all participants of a chat.

get_admins

List all admins of a chat.

get_banned_users

List all banned users in a chat.

promote_admin

Promote a user to admin in a chat.

demote_admin

Demote an admin to a regular member.

ban_user

Ban a user from a chat.

unban_user

Unban a user from a chat.

get_invite_link

Get an invite link for a chat.

export_chat_invite

Export an invite link for a chat.

import_chat_invite

Join a chat using an invite hash.

join_chat_by_link

Join a chat by invite link.

subscribe_public_channel

Subscribe to a public channel or supergroup.

get_messages

Fetch messages from a chat with paging.

list_messages

Filter messages by date or search terms.

list_topics

List forum topics in a supergroup.

send_message

Send a message to a chat.

reply_to_message

Reply to a specific message in a chat.

edit_message

Edit an existing message.

delete_message

Delete a message.

forward_message

Forward a message to another chat.

pin_message

Pin a message in a chat.

unpin_message

Unpin a message.

mark_as_read

Mark messages as read in a chat.

get_message_context

Get surrounding context for a message.

get_history

Retrieve full chat history.

get_pinned_messages

List pinned messages in a chat.

get_last_interaction

Get the most recent message with a contact.

create_poll

Create a poll with options.

list_inline_buttons

Inspect inline keyboard buttons and their indices.

press_inline_button

Trigger an inline keyboard callback by label or index.

send_reaction

Add a reaction to a message.

remove_reaction

Remove a reaction from a message.

get_message_reactions

Get all reactions on a message.

list_contacts

List all contacts.

search_contacts

Search contacts by query.

add_contact

Add a new contact.

delete_contact

Delete a contact.

block_user

Block a user.

unblock_user

Unblock a user.

import_contacts

Bulk import contacts.

export_contacts

Export all contacts as JSON.

get_blocked_users

List blocked users.

get_contact_ids

List all contact IDs.

get_direct_chat_by_contact

Find direct chats with a specific contact.

get_contact_chats

List all chats with a contact.

get_me

Get your user information.

update_profile

Update your profile details.

delete_profile_photo

Remove your profile photo.

get_user_photos

Fetch a user's profile photos.

get_user_status

Get a user's online status.

get_media_info

Get information about media attached to a message.

search_public_chats

Search public chats, channels, or bots.

search_messages

Search messages within a chat.

resolve_username

Resolve a username to an ID.