Telegram MCP for VS Code: Setup & Config

What you can do with Telegram in VS Code

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

• Search unread messages across configured accounts.
• Schedule messages or organize Telegram folders.
• Manage groups, channels, and member permissions.

Before you start: Telegram in VS Code

• 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 VS Code configuration

1. Choose VS Code configuration scope

   For Telegram MCP, open Workspace: .vscode/mcp.json. Merge into servers; preserve existing inputs.

2. Add Telegram MCP to VS Code

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

3. Check Telegram MCP in VS Code

   Telegram MCP: Start in VS Code’s MCP controls; inspect output and trust prompts.

{
  "servers": {
    "telegram-mcp": {
      "type": "stdio",
      "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 VS Code

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

send_file

Look for send_file among VS Code's agent-mode tools after starting Telegram through the MCP controls.

download_media

Look for download_media among VS Code's agent-mode tools after starting Telegram through the MCP controls.

Download Telegram media within configured file-access boundaries.

upload_file

Look for upload_file among VS Code's agent-mode tools after starting Telegram through the MCP controls.

Upload a local file using configured allowed roots.

send_voice

Look for send_voice among VS Code's agent-mode tools after starting Telegram through the MCP controls.

send_sticker

Look for send_sticker among VS Code's agent-mode tools after starting Telegram through the MCP controls.

Send a sticker using an allowed local path.

set_profile_photo

Look for set_profile_photo among VS Code's agent-mode tools after starting Telegram through the MCP controls.

Set a profile photo from a permitted local file.

edit_chat_photo

Look for edit_chat_photo among VS Code's agent-mode tools after starting Telegram through the MCP controls.

Telegram: full stored tool descriptions

Troubleshooting Telegram in VS Code

• Make uv available in the workspace, container, or remote environment hosting Telegram MCP. Start through VS Code's MCP controls; inspect output and trust prompts.
• For Telegram MCP, keep TELEGRAM_API_HASH, TELEGRAM_API_ID, TELEGRAM_EXPOSED_TOOLS, TELEGRAM_SESSION_STRING out of version control; VS Code documents input variables and secret handling.
• Telegram MCP uses stdio here: VS Code 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 VS Code troubleshooting lives in the /clients/vscode guide.

Frequently asked questions