Skip to content
MCP server

Secure Telegram

Telegram MCP server with a separate key per AI client, scoped to chosen chats

Runs locallyStatus and history
Pricing
Open source
Platforms
telegram, CLI, self-hosted
Runs
Locally
Version
0.3.3
Listing updated
2 days ago

About Secure Telegram

Secure Telegram is an open-source MCP server for communication. It runs locally on your machine and is started by your AI client.

Instead of giving every client your full Telegram session, setup creates endpoints, each with its own API key limited to chats or folders you pick and pinned to one of your logged-in accounts. A work agent can be read-only on a Work folder while a personal agent reads and writes private chats, and out-of-scope chats are not addressable at all. Only salted key hashes are stored.

Permissions are eight verbs checked on every call, and writes fail closed. An endpoint can require human confirmation through MCP elicitation, and writes are blocked on clients that lack it. The Telegram session is encrypted at rest with AES-256-GCM, machine-bound by default or PIN-protected, and there is no raw MTProto tool or way for the model to widen its own scope. Per-account pacing aims to lower flood-limit risk, though the author says nothing can guarantee against a ban.

It needs Node 20.10 or newer and a Telegram api_id and api_hash. The README notes the real boundary is your local OS user.

Install

Run in a terminal

claude mcp add secure-telegram-mcp --env TELEGRAM_MCP_ENDPOINT_TOKEN='<TELEGRAM_MCP_ENDPOINT_TOKEN>' -- npx -y secure-telegram-mcp

Add to claude_desktop_config.json

{
  "mcpServers": {
    "secure-telegram-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "secure-telegram-mcp"
      ],
      "env": {
        "TELEGRAM_MCP_ENDPOINT_TOKEN": "<TELEGRAM_MCP_ENDPOINT_TOKEN>"
      }
    }
  }
}

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "secure-telegram-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "secure-telegram-mcp"
      ],
      "env": {
        "TELEGRAM_MCP_ENDPOINT_TOKEN": "<TELEGRAM_MCP_ENDPOINT_TOKEN>"
      }
    }
  }
}

Add to .vscode/mcp.json

{
  "servers": {
    "secure-telegram-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "secure-telegram-mcp"
      ],
      "env": {
        "TELEGRAM_MCP_ENDPOINT_TOKEN": "<TELEGRAM_MCP_ENDPOINT_TOKEN>"
      }
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "secure-telegram-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "secure-telegram-mcp"
      ],
      "env": {
        "TELEGRAM_MCP_ENDPOINT_TOKEN": "<TELEGRAM_MCP_ENDPOINT_TOKEN>"
      }
    }
  }
}

Add to your client's MCP settings (most use this shape)

{
  "mcpServers": {
    "secure-telegram-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "secure-telegram-mcp"
      ],
      "env": {
        "TELEGRAM_MCP_ENDPOINT_TOKEN": "<TELEGRAM_MCP_ENDPOINT_TOKEN>"
      }
    }
  }
}

Configuration

  • TELEGRAM_MCP_ENDPOINT_TOKENThe endpoint's API key. Run 'npx secure-telegram-mcp setup' in a terminal first: it logs in to Telegram and prints the key once.Required

Tools this server provides (18)

Taken from the project documentation; the running server may differ.

get_messages
No description
search_messages
No description
list_dialogs
No description
list_topics
No description
get_chat_info
No description
get_media_info
No description
get_pinned_messages
No description
list_participants
No description
download_media
No description
send_message
No description
edit_message
No description
prepare_media
No description
send_media
No description
save_draft
No description
delete_message
No description
mark_read
No description
send_reaction
No description
forward_message
No description

What it does

Per-client endpoints
Each AI client gets its own key and scope.
Folder-scoped access
Bind an endpoint to folders, chats or channels, with write access opt-in.
Encrypted session
Sessions and policy are AES-256-GCM encrypted at rest.
Confirmed writes
Optional human confirmation, failing closed on clients that cannot ask.
Pacing
Token buckets and a circuit breaker reduce the chance of flood limits.
Audit log
Writes, denials and media egress go to an append-only log.

Good for

  • Let a work assistant read one Telegram folder only
  • Search message history from an AI client without exposing the account
  • Draft or send replies with confirmation
  • Download and describe media under a size cap

Pricing

Open source

Secure Telegram FAQ

Is it read-only?

By default yes; write access is opt-in per endpoint.

What do I need first?

Node.js 20.10 or newer and a Telegram api_id and api_hash from my.telegram.org/apps.

Where is the API key shown?

It is printed once at the end of setup, in a ready-to-paste client config.

Can it avoid bans?

Pacing lowers the risk of flood limits, but nothing can guarantee against a ban.

Is Secure Telegram free?

Yes. Secure Telegram is open source, so you can use and self-host it for free.

How do I add Secure Telegram to Claude Code?

Run this command in your terminal: claude mcp add secure-telegram-mcp --env TELEGRAM_MCP_ENDPOINT_TOKEN='<TELEGRAM_MCP_ENDPOINT_TOKEN>' -- npx -y secure-telegram-mcp

What are the best alternatives to Secure Telegram?

The closest alternatives to Secure Telegram are REA, Agent Roast, Midplane, Leash and Tinplate Edge AI Safety, Security & EU Compliance.

Alternatives to Secure Telegram

  1. REA

    MCP server

    CLI and MCP server that lets coding agents reverse engineer apps and binaries

    Runs locally
    • Open source
    • 464K GitHub stars
    • Developer tools
  2. Agent Roast

    MCP server

    Offline review that flags agent changes which weaken tests, assertions or CI

    Runs locally
    • Open source
    • 4 Hacker News points
    • Developer tools
  3. Midplane

    MCP server

    Postgres gateway for AI agents with table grants, column masking and approval for writes

    Runs locally
    • Open source
    • 5 GitHub stars
    • Databases
  4. Leash

    MCP server

    Review what your AI touched, approve risky actions and undo supported changes

    • 1 tool
    • Remote
    • Free
    • 1 GitHub star
    • Security
  5. SecureCloud

    MCP server

    SentinelOne and IT security catalog, prices, quotes and checkout links for Israel

    • 7 tools
    • Remote
    • Free
    • Security