Telegram MCP server

MCP-Telegram allows Large Language Models to interact with Telegram via the Model Context Protocol (MCP). This server enables AI agents to perform Telegram actions such as sending messages, searching chats, managing drafts, and downloading media using the MTProto protocol.

Getting Started

Prerequisites

• Python 3.10 or higher
• uv package manager - Install following the official uv guide

Installation

Install the MCP-Telegram CLI tool:

uv tool install mcp-telegram

Usage

Login to Telegram

Before using the server, you need to authenticate with your Telegram account:

mcp-telegram login

During the login process, you'll need to provide:

• API ID & API Hash - Get these from my.telegram.org/apps
• Phone Number - Your Telegram phone number in international format (e.g., +1234567890)
• Verification Code - Sent to your Telegram account
• 2FA Password - If you have Two-Factor Authentication enabled

Your credentials will be securely stored for future use.

To logout from the current session:

mcp-telegram logout

To remove all stored session data:

mcp-telegram clear-session

Setting Up the MCP Server

To use MCP-Telegram with clients like Claude Desktop or Cursor, you need to configure the MCP server:

1. Create or update your client's MCP configuration file with:

{
  "mcpServers": {
    "mcp-telegram": {
      "command": "mcp-telegram",
      "args": ["start"],
      "env": {
        "API_ID": "<your_api_id>",
        "API_HASH": "<your_api_hash>"
      }
    }
  }
}

2. If the client can't find the command, use the full path to the executable:

   • Find the path with which mcp-telegram (macOS/Linux) or where mcp-telegram (Windows)
   • Replace the command value with the full path

3. Save the configuration file in the appropriate location:

   • macOS: ~/Library/Application Support/Claude/ or ~/.cursor/
   • Windows: %APPDATA%\Claude\ or %APPDATA%\Cursor\

4. Restart your application

Available Tools

Messaging Tools

• send_message - Send text messages or files to any user, group, or channel
• edit_message - Modify content of previously sent messages
• delete_message - Remove one or multiple messages
• get_messages - Retrieve message history with advanced filtering options

Search & Navigation

• search_dialogs - Find users, groups, and channels by name or username
• message_from_link - Access specific messages using Telegram links

Draft Management

• get_draft - View current message draft for any chat
• set_draft - Create or clear message drafts

Media Handling

• media_download - Download photos, videos, and documents from messages

For detailed parameter information and examples:

mcp-telegram tools

Troubleshooting

Database Locked Errors

If you encounter "database is locked" errors, it's likely because multiple instances of mcp-telegram are using the same session file. Ensure only one instance uses a session file at a time.

To force-stop existing processes:

• macOS / Linux: pkill -f "mcp-telegram"
• Windows: taskkill /F /IM mcp-telegram.exe /T

How to add this MCP server to 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 > MCP and click "Add new global MCP server".

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

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

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 explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.