# Telegram Tools

> Telegram Tools is an open-source MCP server for communication. Read, search and send Telegram messages from coding agents using your own account. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** telegram, CLI, self-hosted
- **Repository:** https://github.com/craft-agent/telegram-tools
- **MCP Registry name:** io.github.craft-agent/telegram-tools
- **Categories:** [communication](https://ai-powered.com/categories/communication)
- **Listing updated:** 2026-11-18

## About

telegram-tools is an unofficial toolkit that gives coding agents access to Telegram chats, messages, received files and sends, with a local mirror that keeps private chats, bots, basic groups and Saved Messages readable without a running sync service. Supergroups and channels are mirrored while on the sync list, older history can be fetched, and chats that are only listed can be read live, up to 100 messages a page.

It is packaged for many harnesses: native plugins for OpenCode V1 and V2, plugins for Claude Code, Codex, Grok Build and Antigravity, a Python plugin for Hermes Agent, and a plain npm MCP server for other hosts. Tools are grouped into toolsets, each with a matching skill. The README names `telegram_account_read` (local state only, no phone number or keys in its result) and `telegram_chat_read`, which supports list, view, topics, search, around and fetch methods.

A read-only flag exists, Codex asks before any tool not marked read-only, and message text, captions, file names and topic titles are treated as data, never instructions. Node.js 24 or later is required, and installs are meant to pin a release tag rather than the default branch.

## Features

- **Chat and message reading:** List, view, search and fetch history from local mirror or live.
- **Received files:** Access files delivered in chats.
- **Send and actions:** Write tools exist alongside read tools, with a read-only option.
- **Account status:** A local-only check of logins, sync state and mirror counts.
- **Many agent harnesses:** Plugins for OpenCode, Claude Code, Codex, Grok Build, Antigravity and Hermes.
- **Prompt-injection stance:** Chat text is handled as data, not instructions.

## Good for

- Search an old Telegram conversation for a detail
- Have a coding agent summarise a group's recent messages
- Check whether the sync service is running and when it last updated
- Send a status message after a build, with approval

## Install

### Claude Code (Terminal)

```sh
claude mcp add telegram-tools -- npx -y @craftsamo/telegram-tools
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "telegram-tools": {
      "command": "npx",
      "args": [
        "-y",
        "@craftsamo/telegram-tools"
      ]
    }
  }
}
```

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

```json
{
  "mcpServers": {
    "telegram-tools": {
      "command": "npx",
      "args": [
        "-y",
        "@craftsamo/telegram-tools"
      ]
    }
  }
}
```

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

```json
{
  "servers": {
    "telegram-tools": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@craftsamo/telegram-tools"
      ]
    }
  }
}
```

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

```json
{
  "mcpServers": {
    "telegram-tools": {
      "command": "npx",
      "args": [
        "-y",
        "@craftsamo/telegram-tools"
      ]
    }
  }
}
```

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

```json
{
  "mcpServers": {
    "telegram-tools": {
      "command": "npx",
      "args": [
        "-y",
        "@craftsamo/telegram-tools"
      ]
    }
  }
}
```

## Tools

- `telegram_account_read`: Local state: logged-in labels, sync status and mirror counts
- `telegram_chat_read`: Find chats and read messages by list, view, topics, search, around or fetch

## FAQ

### Is it official?

No. The registry entry calls it unofficial Telegram tools for coding agents.

### Can I make it read-only?

Yes, there is a `read_only` option and a `--read-only` flag.

### Which Node version?

Node.js 24 or later.

### How should I install it?

From a tagged release, not the default branch, which does not carry the built output.

### Is Telegram Tools free?

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

### How do I add Telegram Tools to Claude Code?

Run this command in your terminal: claude mcp add telegram-tools -- npx -y @craftsamo/telegram-tools

### What are the best alternatives to Telegram Tools?

The closest alternatives to Telegram Tools are TrendRadar, Getmitra, Discord, Zoom and Email Spam Tester.

## Where this comes from

- Description: written from the project's README.
- Install steps: from the official MCP Registry entry.

## Alternatives

- [TrendRadar](https://ai-powered.com/mcp/trendradar): TrendRadar is an open-source MCP server for communication.
- [Getmitra](https://ai-powered.com/mcp/getmitra): Getmitra is an MCP server for communication.
- [Discord](https://ai-powered.com/mcp/discord-2): Discord is a freemium MCP server for communication.
- [Zoom](https://ai-powered.com/mcp/zoom): Zoom is a freemium MCP server for communication.
- [Email Spam Tester](https://ai-powered.com/mcp/email-spam-tester): Email Spam Tester is a free MCP server for communication.
- [Slack_connect](https://ai-powered.com/mcp/slack-connect): Slack_connect is a freemium MCP server for communication.
- [Postmark](https://ai-powered.com/mcp/postmark): Postmark is a freemium MCP server for communication.
- [Gmail](https://ai-powered.com/mcp/gmail-5): Gmail is a freemium MCP server for communication.

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