Installation

Four steps, about five minutes. You need Node.js (tested on 22) and a Telegram account.

git clone https://github.com/vixkosla/telegram-mcp.git
cd telegram-mcp
npm ci

1. Application keys

At my.telegram.org → API development tools, create an application and save its keys to ~/.config/telegram-mcp/config.json:

{"apiId":123456,"apiHash":"32-character hex string"}

Set file permissions to 0600. You can instead use TELEGRAM_API_ID and TELEGRAM_API_HASH, or select another config path with TELEGRAM_MCP_CONFIG.

2. Sign in

node server.mjs login

Enter your phone number, the code from the official Telegram app and, if needed, your two-step verification password. The session is saved to session.txt alongside the server. Telegram’s device list will show a new session under the application name you chose at my.telegram.org.

You can also sign in through the agent: call login_send_code, then login_sign_in. The code expires after 10 minutes.

3. Connect your client

Claude Code

claude mcp add telegram -- node /path/to/telegram-mcp/server.mjs

Codex

# ~/.codex/config.toml
[mcp_servers.telegram]
command = "node"
args = ["/path/to/telegram-mcp/server.mjs"]
startup_timeout_sec = 20

Cursor, Claude Desktop and other clients

{
  "mcpServers": {
    "telegram": {
      "command": "node",
      "args": [
        "/path/to/telegram-mcp/server.mjs"
      ]
    }
  }
}

4. Check the connection

Ask the agent to call status. The response shows the account name and the last four digits of the phone number.

If Telegram is unreachable

If this computer cannot reach Telegram’s MTProto servers, add a proxy to the same config.json:

{"apiId":123456,"apiHash":"…","proxy":"socks5://127.0.0.1:1080"}

socks5:// and socks4:// are supported, including a username and password in the URL.