# Secure Telegram

> Secure Telegram is an open-source MCP server for communication. Telegram MCP server with a separate key per AI client, scoped to chosen chats. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** telegram, CLI, self-hosted, macOS, Windows, Linux
- **Repository:** https://github.com/antonorlov/secure-telegram-mcp
- **MCP Registry name:** io.github.antonorlov/secure-telegram-mcp
- **Categories:** communication, security
- **Listing updated:** 2026-11-15

## About

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.

## Features

- **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

## Install

### Claude Code (Terminal)

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

### Claude Desktop (claude_desktop_config.json)

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

### Cursor (~/.cursor/mcp.json)

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

### VS Code (.vscode/mcp.json)

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

### Windsurf (~/.codeium/windsurf/mcp_config.json)

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

### Other clients (your client's MCP settings (most use this shape))

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

## Tools

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

## 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

- [REA](https://ai-powered.com/mcp/rea): REA is an open-source MCP server for developer tools.
- [Agent Roast](https://ai-powered.com/mcp/agent-roast): Agent Roast is an open-source MCP server for developer tools.
- [Midplane](https://ai-powered.com/mcp/midplane): Midplane is an open-source MCP server for databases.
- [Leash](https://ai-powered.com/mcp/leash): Leash is a free MCP server for security.
- [Tinplate Edge AI Safety, Security & EU Compliance](https://ai-powered.com/mcp/tinplate-edge-ai-safety-security-and-eu-compliance): Tinplate Edge AI Safety, Security & EU Compliance is a freemium MCP server for security.
- [SecureCloud](https://ai-powered.com/mcp/securecloud): SecureCloud is a free MCP server for security.
- [BoardAgent](https://ai-powered.com/mcp/boardagent): BoardAgent is a free MCP server for community directories.
- [Callout](https://ai-powered.com/mcp/callout): Callout is a freemium MCP server for communication.

---
Source: https://ai-powered.com/mcp/secure-telegram
