Telegram MCP server for AI agents

The Telegram MCP Server provides a powerful integration for Claude, Cursor, and other MCP-compatible clients, allowing you to interact with your Telegram account programmatically through the Model Context Protocol (MCP).

Installation & Setup

Using Docker (Recommended)

Docker simplifies dependency management and provides the easiest setup experience:

Clone the repository

git clone https://github.com/chigwell/telegram-mcp.git
cd telegram-mcp

Configure your environment

Copy .env.example to .env

Fill in your Telegram API 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

Get API credentials from my.telegram.org/apps

Generate a session string
```
uv run session_string_generator.py
```
Follow the prompts to authenticate and update your .env file.
Run with Docker Compose
```
docker compose up --build
```
- Use docker compose up -d to run in detached mode (background)
- Press Ctrl+C to stop the server

Manual Installation

If you prefer not to use Docker:

Clone and install dependencies

git clone https://github.com/chigwell/telegram-mcp.git
cd telegram-mcp
uv sync

Configure environment and generate session string (same as steps 2-3 above)
Run the server
```
uv run main.py
```

Configuring Claude & Cursor

Edit your MCP client configuration to include the Telegram MCP server:

Claude Desktop Config

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Cursor Config

Edit ~/.cursor/mcp.json with similar content.

Using Telegram MCP

The MCP server provides numerous tools to interact with Telegram. Here are some common usage examples:

Working with Chats

Listing Your Chats

get_chats(page=1, page_size=20)

Returns a paginated list of your chats with their IDs and titles.

Getting Chat Details

get_chat(chat_id=123456789)

Returns detailed information about a specific chat.

Sending Messages

send_message(chat_id=123456789, message="Hello world!")

Sends a message to the specified chat.

Reading Messages

get_messages(chat_id=123456789, page=1, page_size=20)

Retrieves recent messages from a chat in paginated form.

list_messages(chat_id=123456789, limit=10, search_query="important")

Searches for messages containing specific text.

Managing Groups & Channels

Creating Groups

create_group(title="Project Team", user_ids=[111, 222, 333])

Creates a new group with the specified members.

Invite Links

get_invite_link(chat_id=123456789)

Retrieves an invite link for a group or channel.

join_chat_by_link(link="https://t.me/+AbCdEfGhIjKlMnOp")

Joins a group or channel using an invite link.

User Management

get_participants(chat_id=123456789)

Lists all participants in a group.

promote_admin(chat_id=123456789, user_id=111)

Promotes a user to admin in a group.

ban_user(chat_id=123456789, user_id=111)

Bans a user from a group.

Contact Management

list_contacts()

Lists all your contacts.

add_contact(phone="+1234567890", first_name="John", last_name="Doe")

Adds a new contact.

get_direct_chat_by_contact(contact_query="John")

Finds direct chats with contacts matching a name, username, or phone number.

Account & Profile

get_me()

Returns information about your own account.

update_profile(first_name="New", last_name="Name", about="My bio")

Updates your profile information.

Search Functions

search_public_chats(query="news")

Searches for public chats, channels, or bots.

search_messages(chat_id=123456789, query="important", limit=10)

Searches for messages containing specific text in a chat.

Troubleshooting

Check logs in your MCP client and terminal for errors
Detailed error logs can be found in mcp_errors.log
Regenerate your session string if you change your Telegram password
Use session string authentication instead of file-based sessions if you encounter database lock issues
Move your project to a local path without spaces if you see odd errors with cloud storage services

Advanced Usage

The server includes many additional tools for comprehensive Telegram management:

Message context retrieval
Chat moderation (pinning/unpinning messages)
Notification management (muting/unmuting chats)
Privacy settings management
Chat archiving and organization

All tools can be used via natural language in Claude, Cursor, or any MCP-compatible client.

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

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

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect