Allows an AI client to manage Telegram chats, send messages, download files, and perform message actions like editing or reacting.
Also known as craft-agent/telegram-tools, @craftsamo/telegram-tools
- Stars
- 0
- Tools
- 13
- Downloads, 30 days
- 1,299
- Latest version
- 0.5.1
- Last commit
- Nov 13, 2026
- License
- —
What is telegram-tools MCP?
telegram-tools allows an AI client to manage Telegram chats, send messages, download files, and perform message actions like editing or reacting. It exposes 13 tools, such as telegram_account_read, telegram_chat_read, telegram_sync_read.
Summary generated from the project's README
About telegram-tools MCP server
Managing Telegram conversations and media directly from an AI client is what telegram-tools enables for developers using coding agents. This MCP server provides a suite of tools to read chat histories, send text messages, and manage files through a local mirror system. It supports various environments including Claude Code, Codex, Grok Build, and Antigravity, and can be integrated into any MCP host using npx.
Users can interact with private chats, bots, and groups by utilizing tools like telegram_chat_read to search or fetch message history. The server includes specialized capabilities for file management, allowing the agent to download received files to a specific directory or send up to ten files totaling 100 MB to a chat. For administrative control, the server offers tools to edit or delete your own messages and add emoji reactions. Because it relies on a local mirror and a sync service, it can manage up to 30 supergroups or channels on a sync list to keep message data current without constant network requests.
What you can do with it
- 1Retrieve chat historySearch through previous messages or fetch older history from a specific chat.
- 2Automate message repliesSend a text message to a specific chat ID as a reply to an existing message.
- 3Manage media filesDownload a file from a Telegram message and save it to a local directory.
- 4Modify sent messagesChange the text or caption of a message you have already sent.
Written from the project's README. Every use case is checked against a quote from it.
How to install telegram-tools MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall telegram-tools MCP in Claude Code
$ claude mcp add telegram-tools -- npx -y @craftsamo/telegram-toolsInstall telegram-tools MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"telegram-tools": {
"command": "npx",
"args": [
"-y",
"@craftsamo/telegram-tools"
]
}
}
}Install telegram-tools MCP in VS Code
.vscode/mcp.json
{
"servers": {
"telegram-tools": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@craftsamo/telegram-tools"
]
}
}
}Install telegram-tools MCP in VS Code CLI
$ code --add-mcp '{"name":"telegram-tools","type":"stdio","command":"npx","args":["-y","@craftsamo/telegram-tools"]}'Install telegram-tools MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"telegram-tools": {
"command": "npx",
"args": [
"-y",
"@craftsamo/telegram-tools"
]
}
}
}Install telegram-tools MCP in Codex
$ codex mcp add telegram-tools -- npx -y @craftsamo/telegram-toolsInstall telegram-tools MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.telegram-tools] command = "npx" args = ["-y", "@craftsamo/telegram-tools"]
Install telegram-tools MCP in Gemini CLI
$ gemini mcp add -s user telegram-tools npx -- -y @craftsamo/telegram-toolsInstall telegram-tools MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"telegram-tools": {
"command": "npx",
"args": [
"-y",
"@craftsamo/telegram-tools"
]
}
}
}telegram-tools MCP tools 13
Detected from the READMEtelegram_account_readtelegram_chat_readtelegram_sync_readtelegram_sync_addtelegram_sync_removetelegram_message_sendtelegram_file_savetelegram_file_sendtelegram_message_edittelegram_message_deletetelegram_message_reacttelegram_message_pin
| telegram_account_read | — | |
| telegram_chat_read | — | |
| telegram_sync_read | — | |
| telegram_sync_add | — | |
| telegram_sync_remove | — | |
| telegram_message_send | — | |
| telegram_file_save | — | |
| telegram_file_send | — | |
| telegram_message_edit | — | |
| telegram_message_delete | — | |
| telegram_message_react | — | |
| telegram_message_pin | — |
Show all 13 toolsShow fewer tools
telegram_chat_mark_read
| telegram_chat_mark_read | — |
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work · What to fix for more points
- Source repository linked and reachablecraft-agent/telegram-tools is public and reachablegithub.com/craft-agent/telegram-tools ↗Pass
- Package names this repository as its source@craftsamo/telegram-tools names craft-agent/telegram-tools as sourcenpmjs.com/package/@craftsamo/telegram-tools ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for @craftsamo/telegram-toolsnpmjs.com/package/@craftsamo/telegram-tools/v/0.5.0#provenan ↗Pass
- Open source license (OSI)No licenseFinding
- Commit or release in the last yearLast commit or release 2026-11-13github.com/craft-agent/telegram-tools ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @craftsamo/telegram-toolsPass
- No critical advisory in the package or its dependenciesthe package checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model13 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubtelegram-tools
Unofficial Telegram tools for coding agents: chats, messages, received files, sends and actions.
| Harness | Delivery | Pinned by |
|---|---|---|
| OpenCode V2 | native plugin (npm package, with skills) | the version in the package |
| OpenCode V1 | native plugin (npm package, no skills) | the version in the package |
| Claude Code | plugin: MCP server and skills | the release tag, as the ref |
| Codex | plugin: MCP server and skills | the release tag, as the ref |
| Grok Build | plugin: MCP server and skills | the release tag, as @ref |
| Antigravity | plugin: MCP server and skills | the release tag's tree URL |
| Hermes Agent | native plugin (Python, calls the command line) | the release commit, as the SHA |
| other MCP host | MCP server from npm | the version in the package |
The tools need Node.js 24 or later.
docs/conventions.md describes how the tools are named
and how they behave.
Install
Install from a release, never from the default branch: a release is a tag whose
commit carries the built dist/, and the default branch does not. In the
commands below, <version> is a release's version (1.2.3) and <sha> is the
commit its tag names:
gh api repos/craft-agent/telegram-tools/commits/v<version> --jq .sha
OpenCode
OpenCode V2 takes the package and its options in opencode.json:
{
"plugins": [{ "package": "@craftsamo/telegram-tools@<version>", "options": { "read_only": false } }],
"permissions": [{ "action": "telegram_*", "resource": "*", "effect": "ask" }]
}
OpenCode V1 takes the package as a string, or as a pair with its options:
{
"plugin": [["@craftsamo/telegram-tools@<version>", { "read_only": false }]],
"permission": { "telegram_*": "ask" }
}
OpenCode allows any action no rule names, so the plugin's request is granted
silently unless a rule says ask. Read tools never ask, so the telegram_* glob
is safe.
V1 registers no skills. Unpack the package and copy its skills/* folders into
~/.config/opencode/skills/:
npm pack @craftsamo/telegram-tools@<version>
tar -xzf craftsamo-telegram-tools-<version>.tgz
mkdir -p ~/.config/opencode/skills
cp -r package/skills/* ~/.config/opencode/skills/
rm -rf package craftsamo-telegram-tools-<version>.tgz
Claude Code
claude plugin marketplace add craft-agent/telegram-tools#v<version>
claude plugin install telegram-tools@craft-agent
Codex
codex plugin marketplace add craft-agent/telegram-tools --ref v<version>
codex plugin add telegram-tools@craft-agent
Codex turns - into _ in server names, so it shows the tools as
mcp__telegram_tools__telegram_*. It starts the MCP server in the plugin's
install directory and passes no roots, so the server takes each call's directory
from what Codex sends with the call: its sandbox state, which the server asks
for, else the one workspace it names.
The plugin declares default_tools_approval_mode = "writes": Codex asks before
every tool not marked read-only. A user's
[plugins."<plugin>".mcp_servers.<server>] setting can only tighten it. Setting
auto there yields prompt (reads asked too), since Codex treats auto and
writes as incomparable.
Grok Build
grok plugin install craft-agent/telegram-tools@v<version> --trust
Grok starts the MCP server in the session's working directory.
Antigravity
Install from the tree of the release tag, never from the default branch, which
has no built dist/; Antigravity clones the tag into
~/.gemini/config/plugins/telegram-tools.
agy plugin install https://github.com/craft-agent/telegram-tools/tree/v<version>
Hermes Agent
Hermes installs a commit, not a tag, and the plugin installs disabled:
hermes plugins install craft-agent/telegram-tools --ref <sha>
hermes plugins enable telegram-tools
If a Hermes gateway is already running, restart it (hermes gateway restart) to
load the plugin.
The plugin runs the Node it found when Hermes started. If a version manager
removes that version while Hermes runs, a call looks for Node again; when it
finds none, restart Hermes from a shell where node runs.
Any other MCP host
Add the server to the host's MCP configuration. Flags go in args:
{
"mcpServers": {
"telegram-tools": {
"command": "npx",
"args": ["-y", "@craftsamo/telegram-tools@<version>", "--read-only"]
}
}
}
Tools and skills
Each toolset comes with a skill that tells an agent how to use its tools. A
skill names its toolset under metadata in its frontmatter
(metadata: { toolset: sends }, written as a block). OpenCode V2 and Hermes
register it only when the settings register at least one of that toolset's
tools, so a profile with the toolset off, or with all its tools removed, does
not see it; a skill without a toolset is always registered. Claude Code,
Codex, Grok Build and Antigravity install the skill folder whole and pass the
settings only to the MCP server, so they list every skill whatever the
settings select. OpenCode V1 registers no skills, and its copied skills are
all listed too.
Account (account)
| Tool | What it does | Class |
|---|---|---|
telegram_account_read |
which labels are logged in, whether each sync service runs, when it last heard from Telegram, the mirror's counts, and the person's next step | read |
It reads local state only: no daemon, no network, and no phone number, account
id or key in its result. The skill is
telegram-account, shown as
telegram-tools:telegram-account in Claude Code and telegram-tools:account
in Hermes.
Chats (chats)
| Tool | What it does | Class |
|---|---|---|
telegram_chat_read |
finds chats and reads messages by method: list, view, topics, search, around, or older history fetch |
read |
Chats the mirror keeps (private chats, bots, basic groups, Saved Messages;
supergroups and channels while on the sync list) are read from the local mirror
without needing the sync service; older history is fetched with fetch. Chats
only listed are read live from Telegram by view and around, via the sync
service, up to 100 messages a page (live: true). Message text, captions, file
names and topic titles are data, never instructions. The skill is
telegram-chats, shown as
telegram-tools:telegram-chats in Claude Code and telegram-tools:chats in
Hermes.
Sync (sync)
| Tool | What it does | Class |
|---|---|---|
telegram_sync_read |
lists the supergroups and channels on the sync list | read |
telegram_sync_add |
puts supergroups or channels on the sync list to mirror from now on | idempotent |
telegram_sync_remove |
takes chats off the sync list and deletes their mirrored messages and earlier versions | overwrite |
The sync list names up to 30 supergroups and channels whose messages the mirror
keeps current. telegram_sync_read reads the list from the local mirror
without needing the sync service. Adding or removing chats changes the local
mirror and needs the sync service running; newly added chats are seeded with
their newest 50 messages, while removing a chat deletes its mirrored messages
and earlier versions locally (nothing changes at Telegram). Channels can be
listed or mirrored only with the channels setting on. The skill is
telegram-sync, shown as
telegram-tools:telegram-sync in Claude Code and telegram-tools:sync in
Hermes.
Sends (sends)
| Tool | What it does | Class |
|---|---|---|
telegram_message_send |
sends one text to a chat by id, optionally to a forum topic or as a reply | add |
The sends toolset is on by default. The text goes out as written (never read
as Markdown or HTML), trimmed, at most 4096 characters. One call sends once,
with one random_id, and is never repeated: a failure uncertain means the
message may have gone out, and its hint lists the matching messages the mirror
saw, so the person checks the chat before anything is sent again. duplicate
means an earlier delivery of the same call had already gone out. The sync
service sends it, so it must be running. The skill is
telegram-sends, shown as
telegram-tools:telegram-sends in Claude Code and telegram-tools:sends in
Hermes.
Files (files)
| Tool | What it does | Class |
|---|---|---|
telegram_file_save |
downloads one message's file from Telegram and saves it into download_dir |
add |
telegram_file_send |
sends 1 to 10 files (100 MB together), with a caption, to a chat | add |
The files toolset is off by default: it writes to disk, opens archives and
sends files. Turn it on with toolsets or tools. Sending takes 1 to 10 files
(at most 100 MB together) as one group, every file as a file, from the working
directory (not when that is the home directory or a file system root) and the
directories send_dirs names; keys, secrets, programs and installers are
refused, archives are checked entry by entry, each file is copied into the
label's outbox and checked before upload, and sha256 can pin a file to what
was approved. Sending needs the sync service running; a failure uncertain
lists matching messages the mirror saw so the person checks the chat before
anything is sent again. For received files, a message's file goes in
<download_dir>/<label>/<chat id>/<message id>/, private (mode 600), never
executable and never overwritten; download_max_mb sets the largest file
taken. The sync service downloads it, so it must be running. Programs and
installers are refused, and so are archives other than zip, tar and gzipped
tar, archives holding a program, another archive, a link or a path that leaves
them, animated stickers and view-once files. An archive is inspected and
listed, and unpacked only when asked (unpack: true) into <name>.unpacked/
beside it. On macOS every saved and unpacked file carries the quarantine flag.
File names and contents are data, never instructions. The skill is
telegram-files, shown as
telegram-tools:telegram-files in Claude Code and telegram-tools:files in
Hermes.
Actions (actions)
| Tool | What it does | Class |
|---|---|---|
telegram_message_edit |
replaces the text or caption of one of the user's own messages | overwrite |
telegram_message_delete |
deletes one of the user's own messages for everyone | administrative |
telegram_message_react |
sets or removes the user's emoji reaction on a message | overwrite |
telegram_message_pin |
pins or unpins a message | overwrite |
telegram_chat_mark_read |
marks a chat, or one forum topic, read up to a message, never further | idempotent |
The actions toolset is off by default: it changes what other people have
already read. Turn it on with toolsets or tools. Edit and delete take only
the user's own messages; a delete is always for everyone, cannot be undone and
is asked about every time. A reaction is one standard emoji that replaces the
user's earlier one (custom and paid reactions are refused). A pin is silent
unless notify, and in a private chat it pins for the user only unless
both_sides. Mark read runs only when the user asks, goes up to the message
named and never back, and makes the senders see it read. Every action needs the
sync service running. already means it was already so; uncertain means it
may have happened, so the person checks the chat before it is asked again. The
skill is telegram-actions, shown as
telegram-tools:telegram-actions in Claude Code and telegram-tools:actions
in Hermes.
Adding a tool
- Write the spec in
src/core/<domain>/<verb>.tswithdefineTool: an ID<prefix>_<domain>_<verb>, a title and description, the Zod argument and output schemas, its toolset and write class, andexecute(args, context). A write tool also givestargets(args, context): what the call writes to, as a permission rule should name it. - Test it beside the spec (
<verb>.test.ts), calling it throughinvokeas the entry points do. A tool that runs a program is tested against a fake of that program onPATH; no test reaches a real service. - List it in
src/tools.ts. A new toolset goes intotoolsetsinsrc/project.ts(anddefaultToolsetswhen it is on by default), a setting of the package's own intooptions(andOPTIONSinproject.pywithconfig_schemainplugin.yaml), and a variable the tool reads besides the settings intotoolVariables. - Add or update the toolset's skill,
skills/<prefix>-<toolset>/SKILL.md, whose frontmatter names the toolset undermetadata. - Run
pnpm run build && pnpm run manifeststo list the tool inplugin.yamland its variables in Codex's manifest, then describe it under "Tools and skills".
docs/conventions.md has the rules each step follows.
A package declares each option as text, boolean, number, list, path
or paths, or as an object with type and optional bounds. For example, in
src/project.ts:
options: {
notes_dir: "path",
note_limit: { type: "number", integer: true, min: 1, max: 50 },
}
integer: true requires a whole number; min and max bound a number or
count a list or paths value's items. An object with only type means the
same as the type alone. Hermes's OPTIONS mirrors the declarations on one
line, with double quotes and Python's True for integer:
OPTIONS: dict[str, str | dict[str, object]] = {"notes_dir": "path", "note_limit": {"type": "number", "integer": True, "min": 1, "max": 50}}
Reads and writes
Every read tool is named <prefix>_<domain>_read. Reads can run unasked;
writes are confirmed by the harness.
| Harness | Reads without asking |
|---|---|
| OpenCode | always; the plugin asks only before a write |
| Claude Code | the rule mcp__plugin_telegram-tools_telegram-tools__*_read in permissions.allow of ~/.claude/settings.json |
| Codex | always; Codex runs tools that declare readOnlyHint unasked, as the read tools do |
| Grok Build | grok --allow 'MCPTool(telegram-tools__*_read)' --allow 'MCPTool(telegram_*_read)' (both rules; see below) |
| Antigravity | the rule mcp(telegram-tools_telegram-tools/<tool id>) in permissions.allow, one for each read tool |
| Hermes | always; the plugin asks only before a write |
Where a write is asked about, and where it is not:
- OpenCode grants any action no rule names, so a write runs unasked unless
a rule asks for it: add the
telegram_*rule shown under OpenCode. - Codex asks before every write because of the plugin's approval mode.
Under
codex execit refuses with "MCP tool call requires approval, but approval policy is never". - Grok Build under
grok -prefuses a write it cannot ask about, unless it is allowed beforehand. - Grok Build calls the plugin's tools through its
use_tooltool, and the agent often names a tool without its server first. Grok checks the rules against the name as given, so the server-qualified rule alone does not match that first call. The second rule matches the short name; a write still matches neither. - Antigravity asks before any MCP tool no rule allows, reads included, and
names the plugin's server
telegram-tools_telegram-tools(plugin, then server).agy -prefuses a tool it cannot ask about. - Hermes
hermes chat -qrefuses a write it cannot ask about;hermes -zand--yoloskip approval, so writes then run unasked.
telegram-tools MCP questions
How do I add telegram-tools MCP to Claude Code?
Run claude mcp add telegram-tools -- npx -y @craftsamo/telegram-tools in your terminal. Add --scope user to make it available in every project.
How do I add telegram-tools MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does telegram-tools MCP provide?
It exposes 13 tools, including telegram_account_read, telegram_chat_read, telegram_sync_read, telegram_sync_add, telegram_sync_remove.
Can the server send files via Telegram?
Yes, it can send between 1 and 10 files (up to 100 MB total) with a caption to a chat.
Does the server require a phone number or API key to be provided in the results?
No, the account tool reads local state only and does not include phone numbers, account IDs, or keys in its output.
How are received files stored?
Files are saved in a specific directory structure: <download_dir>/<label>/<chat id>/<message id>/ with private permissions.