Telegram MCP for Windsurf: Setup & Config

What you can do with Telegram in Windsurf

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

• Review chat history and prepare responses.
• Search unread messages across configured accounts.
• Send or download media within approved file roots.

Before you start: Telegram in Windsurf

• 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 Windsurf configuration

1. Choose Windsurf configuration scope

   For Telegram MCP, open macOS/Linux: ~/.codeium/windsurf/mcp_config.json Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json. Merge into mcpServers; remote endpoints use serverUrl.

2. Add Telegram MCP to Windsurf

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

3. Check Telegram MCP in Windsurf

   Telegram MCP: Refresh MCP in Windsurf settings and inspect Cascade’s 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 Windsurf

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

send_file

After refreshing Telegram in Windsurf settings, check Cascade's tool list for send_file.

Send a local file from an allowed filesystem root.

download_media

After refreshing Telegram in Windsurf settings, check Cascade's tool list for download_media.

Download Telegram media within configured file-access boundaries.

upload_file

After refreshing Telegram in Windsurf settings, check Cascade's tool list for upload_file.

send_voice

After refreshing Telegram in Windsurf settings, check Cascade's tool list for send_voice.

Send a voice note from a permitted file path.

send_sticker

After refreshing Telegram in Windsurf settings, check Cascade's tool list for send_sticker.

set_profile_photo

After refreshing Telegram in Windsurf settings, check Cascade's tool list for set_profile_photo.

edit_chat_photo

After refreshing Telegram in Windsurf settings, check Cascade's tool list for edit_chat_photo.

Change a chat photo using a permitted local file.

Telegram: full stored tool descriptions

Troubleshooting Telegram in Windsurf

• Check uv on the machine running Windsurf's MCP integration for Telegram MCP; refresh MCP and inspect Cascade's tools.
• Check TELEGRAM_API_HASH, TELEGRAM_API_ID, TELEGRAM_EXPOSED_TOOLS, TELEGRAM_SESSION_STRING for Telegram MCP; do not bypass a Windsurf permission error with a broad administrator token.
• Telegram MCP uses stdio here: Windsurf 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 Windsurf troubleshooting lives in the /clients/windsurf guide.

Frequently asked questions