# Telegram (tg-mcp)

> Telegram (tg-mcp) is an open-source MCP server for communication. Remote MCP server that lets Claude, ChatGPT or Gemini read your Telegram chats. It runs as a hosted remote server, so there is nothing to install locally.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** self-hosted, API, Web
- **Website:** https://tgmcp.dev
- **Repository:** https://github.com/qelphybox/tg-mcp
- **MCP Registry name:** io.github.qelphybox/tg-mcp
- **Categories:** communication
- **Listing updated:** 2026-11-14

## About

tg-mcp connects a personal Telegram account, not a bot, to an AI client. You add one URL as a custom connector, scan a QR code in Telegram under Settings, Devices, Link Desktop Device, and no API id or hash is needed. Reading is always included. Writing is opt-in: on the consent screen you can allow drafts that you send yourself, or messages to chats you choose, with reactions and read marks in those chats.

The site is candid about trust. Messages pass through the server's memory while your AI reads a chat, and your questions go to your AI provider. It suggests self-hosting for anyone who does not want to rely on the public instance, and the project publishes a 15 MB Docker image for amd64 and arm64. The session is stored encrypted with a key held by the AI app.

The maker, an independent developer, states that it is unofficial and not affiliated with Telegram. It uses Telegram's API through its own registered app, stays within rate limits and waits when asked, though the site says nobody can promise an account will never be affected.

## Features

- **QR code login:** Links a personal account the way Telegram Desktop does, with no API key.
- **Read and search chats:** Lists chats, reads messages and handles media such as photos and voice messages.
- **Opt-in writing:** Drafts and sent messages are separate permissions you tick on the consent screen.
- **Chat selection for sending:** Sending is limited to chats you choose, such as folders or recent chats.
- **Self-hosting:** One Docker command runs your own copy of the MIT-licensed server.
- **Works in many clients:** Claude, ChatGPT, Gemini, Claude Code, Cursor and other streamable-HTTP clients.

## Good for

- Catch up on unread chats after time away
- Search old conversations for a detail
- Summarise a busy group chat
- Draft a reply that you review and send yourself
- Transcribe voice messages through your AI

## Install

### Claude Code (Terminal)

```sh
claude mcp add --transport http tg-mcp https://connector.tgmcp.dev/mcp
```

### Claude Desktop (Settings → Connectors → Add custom connector)

```sh
https://connector.tgmcp.dev/mcp
```

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

```json
{
  "mcpServers": {
    "tg-mcp": {
      "url": "https://connector.tgmcp.dev/mcp"
    }
  }
}
```

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

```json
{
  "servers": {
    "tg-mcp": {
      "type": "http",
      "url": "https://connector.tgmcp.dev/mcp"
    }
  }
}
```

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

```json
{
  "mcpServers": {
    "tg-mcp": {
      "serverUrl": "https://connector.tgmcp.dev/mcp"
    }
  }
}
```

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

```json
{
  "mcpServers": {
    "tg-mcp": {
      "type": "http",
      "url": "https://connector.tgmcp.dev/mcp"
    }
  }
}
```

## Tools

- `whoami`: Returns the connected account and its chat folders.
- `list_chats`: Lists chats, most recent first, with unread counts and previews; supports folders and unread-only filtering.
- `get_messages`: Returns messages of one chat with sender, date, text and media details.
- `save_draft`: Puts text into a chat's message field for you to send; needs the drafts permission.
- `send_message`: Sends a message to a chosen chat; needs the send permission.
- `react`: Reacts to a message in an allowed chat.
- `mark_read`: Marks messages as read in an allowed chat.

## FAQ

### Is it free?

Yes. The site says there is no sign-up, payment or API key, and the code is MIT licensed.

### How is it different from local Telegram MCP servers?

It is a remote server added by URL, so it also works in web and mobile AI apps, with no Python or Node install or API id.

### Can the AI send messages without asking?

Only if you tick Send messages and pick the chats. Whether you are asked first is up to your AI app.

### Can Telegram block my account?

It uses the official API and respects rate limits, but the site says nobody can honestly promise nothing will ever happen.

### Is Telegram (tg-mcp) free?

Yes. Telegram (tg-mcp) is open source, so you can use and self-host it for free.

### How do I add Telegram (tg-mcp) to Claude Code?

Run this command in your terminal: claude mcp add --transport http tg-mcp https://connector.tgmcp.dev/mcp

### What are the best alternatives to Telegram (tg-mcp)?

The closest alternatives to Telegram (tg-mcp) are BoardAgent, Callout, nicemails, SOMMON Office and PostBaton.

## Alternatives

- [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.
- [nicemails](https://ai-powered.com/mcp/nicemails): nicemails is a freemium MCP server for communication.
- [SOMMON Office](https://ai-powered.com/mcp/sommon-office): SOMMON Office is a paid MCP server for communication.
- [PostBaton](https://ai-powered.com/mcp/postbaton): PostBaton is a freemium MCP server for marketing and seo.
- [MeetBetr](https://ai-powered.com/mcp/meetbetr): MeetBetr is a free MCP server for productivity.
- [Host Tools](https://ai-powered.com/mcp/host-tools): Host Tools is an MCP server for home services.
- [iMessage MCP](https://ai-powered.com/mcp/imessage-mcp): iMessage MCP is an open-source MCP server for communication.

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