How to add Telegram MCP Server (chigwell) to Windsurf

Full Telegram user-account MCP via MTProto: read chats, manage groups, send messages Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

Last updated June 15, 2026 · 1.2k★ · stdio · apikey

Windsurf config for Telegram MCP Server (chigwell)

git clone https://github.com/chigwell/telegram-mcp && cd telegram-mcp && uv sync && uv run main.py

{
  "mcpServers": {
    "telegram-mcp-server-chigwell": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/telegram-mcp",
        "run",
        "main.py"
      ],
      "env": {
        "TELEGRAM_API_ID": "<your-telegram-api-id>",
        "TELEGRAM_API_HASH": "<your-telegram-api-hash>",
        "TELEGRAM_SESSION_STRING": "<your-generated-session-string>"
      }
    }
  }
}

Setup steps

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

Before you start

Python 3.10+ (uv recommended for dependency management)
A Telegram account (this controls a real user account, not a bot)
TELEGRAM_API_ID and TELEGRAM_API_HASH obtained from https://my.telegram.org/apps
A Telegram session string generated with the bundled session_string_generator.py (QR or phone login)
An MCP client such as Claude Desktop or Cursor

What Telegram MCP Server (chigwell) can do in Windsurf

get_chats / list_chats

Paginated/filterable list of chats with metadata

send_message

Send a message to a user, group, or channel

edit_message / delete_message

Edit or delete an existing message

forward_message

Forward a message to another chat

search_messages

Search message history across chats

create_group / create_channel

Create new groups or channels

invite_user / manage admins, bans, permissions

Group administration: invites, admin rights, bans, permissions, slow mode

list_contacts / add_contact / block / unblock

Contact management including block/unblock and import/export

Security

Connects as a full Telegram user account, so the session string grants complete access to your account — treat it like a password and never share it. Pin to a release tag/commit when cloning to avoid pulling unreviewed upstream changes.

Telegram MCP Server (chigwell) + Windsurf FAQ

Where is the Windsurf config file?

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

Is Telegram MCP Server (chigwell) safe to use with Windsurf?

Is this a bot or my real account?

It logs in as your real Telegram user account via MTProto/Telethon, so it has full access your account has — not the limited Telegram Bot API surface.

Where do I get the API credentials?

Create an application at https://my.telegram.org/apps to obtain your API_ID and API_HASH; there is no charge.

How does login work — do I re-enter a code every time?

No. You generate a session string once with the bundled session_string_generator.py (QR or phone), store it in .env, and it reuses that session.

View repo Full Telegram MCP Server (chigwell) page