Telegram Tools
Read, search and send Telegram messages from coding agents using your own account
- 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-toolsAdd to claude_desktop_config.json
{
"mcpServers": {
"telegram-tools": {
"command": "npx",
"args": [
"-y",
"@craftsamo/telegram-tools"
]
}
}
}Add to ~/.cursor/mcp.json
{
"mcpServers": {
"telegram-tools": {
"command": "npx",
"args": [
"-y",
"@craftsamo/telegram-tools"
]
}
}
}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.

