Skip to content
MCP server

Telegram Tools

Read, search and send Telegram messages from coding agents using your own account

Runs locallyStatus and history
Install
Pricing
Open source
Platforms
telegram, CLI, self-hosted
Runs
Locally
Version
0.6.0
Listing updated
today

Similar MCP servers

About Telegram Tools

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

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.

Install

Run in a terminal

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

Add to claude_desktop_config.json

{
  "mcpServers": {
    "telegram-tools": {
      "command": "npx",
      "args": [
        "-y",
        "@craftsamo/telegram-tools"
      ]
    }
  }
}
Install in CursorOpens Cursor, which asks you to confirm. Or add it by hand:

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "telegram-tools": {
      "command": "npx",
      "args": [
        "-y",
        "@craftsamo/telegram-tools"
      ]
    }
  }
}
Install in VS CodeOpens VS Code, which asks you to confirm. Or add it by hand:

Add to .vscode/mcp.json

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

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

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

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

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

Using several servers? Build one config file with the MCP config generator.

Tools this server provides (2)

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

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

What it does

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

Pricing

Open source

Free npm package; licence in the repo

More servers for the same service

Telegram Tools 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.

How AIPoweredBot checks servers