How to add Telegram MCP server to Windsurf

Bridge AI assistants to your Telegram account: read dialogs, summarize unread messages, mark as read, and send drafts. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

Last updated June 14, 2026 · 334★ · stdio · apikey

Windsurf config for Telegram MCP server

npx -y @chaindead/telegram-mcp

{
  "mcpServers": {
    "telegram-mcp-server": {
      "command": "telegram-mcp",
      "args": [],
      "env": {
        "TG_APP_ID": "<your-app-id>",
        "TG_API_HASH": "<your-api-hash>",
        "PATH": "<path_to_telegram-mcp_binary_dir>",
        "HOME": "<path_to_your_home_directory"
      }
    }
  }
}

Setup steps

1Open Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
2Paste the Telegram MCP server config below.
3Fill in placeholder secrets, then save.
4Click Refresh in the MCP panel.
5Telegram MCP server's tools become available to Cascade.

Before you start

A Telegram account
Telegram API ID and API hash from https://my.telegram.org/auth
One-time CLI authorization: telegram-mcp auth --app-id <id> --api-hash <hash> --phone <phone> (add --password for 2FA)
Install via Homebrew, release binary, or go install (Go 1.24+); alternatively run via npx (macOS, Linux, Windows)

What Telegram MCP server can do in Windsurf

tg_me

Get current account information.

tg_dialogs

List dialogs with an optional unread filter.

tg_read

Mark a dialog as read.

tg_dialog

Retrieve messages from a specific dialog.

tg_send

Send draft messages to any dialog.

Security

Connects to your personal Telegram account via MTProto. Requires a Telegram API ID and hash from https://my.telegram.org/auth and a one-time CLI authorization (telegram-mcp auth --app-id <id> --api-hash <hash> --phone <phone>); add --password for 2FA. Review the Telegram API Terms of Service first, as misuse may result in account suspension. Credentials (TG_APP_ID, TG_API_HASH) are passed as environment variables.

Telegram MCP server + Windsurf FAQ

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the Telegram MCP server config there under the "mcpServers" key and restart the client.

Is Telegram MCP server safe to use with Windsurf?

How do I authorize the server?

Get an API ID and hash from https://my.telegram.org/auth, then run: telegram-mcp auth --app-id <your-api-id> --api-hash <your-api-hash> --phone <your-phone-number>, and enter the code Telegram sends you. If you have 2FA enabled, add --password <2fa_password>; to override an existing session, add --new.

Can I run it without installing a binary?

Yes. You can run the latest version directly with npx on macOS, Linux, and Windows: npx -y @chaindead/telegram-mcp. Auth and client config use the npx command form (e.g. command "npx" with args ["-y", "@chaindead/telegram-mcp"]).

My MCP client rejects the server's tools (e.g. VS Code). What can I do?

Some clients do not support JSON Schema Draft 2020-12 (the default). Override the schema version with the --schema-version flag or the TG_SCHEMA_VERSION environment variable; Draft-07 (https://json-schema.org/draft-07/schema#) is recommended for VS Code.

View repo Full Telegram MCP server page