Telegram MCP for Cursor: Setup & Config

What you can do with Telegram in Cursor

Use Telegram account workflows from MCP with multi-account routing and configurable tool exposure.

• Review chat history and prepare responses.
• Manage groups, channels, and member permissions.
• Send or download media within approved file roots.

Before you start: Telegram in Cursor

• Python 3.10+
• uv for this source-checkout configuration
• Clone of chigwell/telegram-mcp with uv sync completed
• Telegram API credentials and an authorized session
• An MCP client

Replace the checkout path. Generate a session using the repository session generator before starting. Do not install the unrelated telegram-mcp package from PyPI. File tools need explicitly allowed roots; read-only exposure is not an account sandbox.

Telegram Cursor configuration

1. Choose Cursor configuration scope

   For Telegram MCP, open Project: .cursor/mcp.json User: ~/.cursor/mcp.json. Merge into mcpServers at project or user scope.

2. Add Telegram MCP to Cursor

   Use the telegram-mcp entry below in mcpServers. Keep Telegram MCP's documented stdio connection fields and your other Cursor entries.

3. Check Telegram MCP in Cursor

   Telegram MCP: Enable in Cursor’s MCP settings; inspect tools.

{
  "mcpServers": {
    "telegram-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/full/path/to/telegram-mcp",
        "run",
        "main.py"
      ],
      "env": {
        "TELEGRAM_API_ID": "<Telegram application API ID>",
        "TELEGRAM_API_HASH": "<Telegram application API hash>",
        "TELEGRAM_SESSION_STRING": "<Authorized Telegram session string>",
        "TELEGRAM_EXPOSED_TOOLS": "<Optional all or read-only tool exposure>"
      }
    }
  }
}

Telegram tools available to Cursor

Telegram's stored tool list documents 7 tools; compare it with Cursor's connected tool list, because the stored list is not a live check.

send_file

Find send_file under Telegram in Cursor's MCP settings; inspect its arguments when the agent requests a call.

Send a local file from an allowed filesystem root.

download_media

Find download_media under Telegram in Cursor's MCP settings; inspect its arguments when the agent requests a call.

upload_file

Find upload_file under Telegram in Cursor's MCP settings; inspect its arguments when the agent requests a call.

send_voice

Find send_voice under Telegram in Cursor's MCP settings; inspect its arguments when the agent requests a call.

send_sticker

Find send_sticker under Telegram in Cursor's MCP settings; inspect its arguments when the agent requests a call.

Send a sticker using an allowed local path.

set_profile_photo

Find set_profile_photo under Telegram in Cursor's MCP settings; inspect its arguments when the agent requests a call.

Set a profile photo from a permitted local file.

edit_chat_photo

Find edit_chat_photo under Telegram in Cursor's MCP settings; inspect its arguments when the agent requests a call.

Change a chat photo using a permitted local file.

Telegram: full stored tool descriptions

Troubleshooting Telegram in Cursor

• Cursor must find uv for Telegram MCP. Enable the project/user entry in MCP settings and inspect its tools.
• Review TELEGRAM_API_HASH, TELEGRAM_API_ID, TELEGRAM_EXPOSED_TOOLS, TELEGRAM_SESSION_STRING for Telegram MCP before sharing project .cursor/mcp.json; project scope travels with the repository.
• Telegram MCP uses stdio here: Cursor must keep the configured process running; protocol output belongs on stdout and diagnostics on stderr.
• Known limitation: Session credentials grant normal Telegram account authority.
• Known limitation: The PyPI package with the same name is unrelated.
• Known limitation: File tools require allowed-root configuration.
• General Cursor troubleshooting lives in the /clients/cursor guide.

Frequently asked questions