Telegram MCP Server & CLI
A free, open source Telegram MCP server and CLI that lets Claude Code, Codex, Cursor and other AI agents read, search and answer your real Telegram chats.
0.0(0 ratings)- 1
Log in once in a terminal, with your API ID and hash.
Telegram asks for your phone number, the code it sends you and your two-step password if you have one. Put the session string it prints into TELEGRAM_SESSION below.
export TELEGRAM_API_ID=1234567
export TELEGRAM_API_HASH=your-api-hash
npx -y @thenavidm/telegram-mcp-cli@latest login - 2
Add it with a single command in a terminal.
claude mcp add telegram \
-e TELEGRAM_API_ID=1234567 \
-e TELEGRAM_API_HASH=your-api-hash \
-e TELEGRAM_SESSION=your-session-string \
-- npx -y @thenavidm/telegram-mcp-cli@latest - 3
In Claude Code, type /mcp. Telegram should show as connected.
/mcp
- 1
Log in once in a terminal, with your API ID and hash.
Telegram asks for your phone number, the code it sends you and your two-step password if you have one. Put the session string it prints into TELEGRAM_SESSION below.
$env:TELEGRAM_API_ID = "1234567"
$env:TELEGRAM_API_HASH = "your-api-hash"
npx -y @thenavidm/telegram-mcp-cli@latest login - 2
Add it with a single command in a terminal.
claude mcp add telegram -e TELEGRAM_API_ID="1234567" -e TELEGRAM_API_HASH="your-api-hash" -e TELEGRAM_SESSION="your-session-string" -- npx -y @thenavidm/telegram-mcp-cli@latest - 3
In Claude Code, type /mcp. Telegram should show as connected.
/mcp
- 1
Log in once in a terminal, with your API ID and hash.
Telegram asks for your phone number, the code it sends you and your two-step password if you have one. Put the session string it prints into TELEGRAM_SESSION below.
export TELEGRAM_API_ID=1234567
export TELEGRAM_API_HASH=your-api-hash
npx -y @thenavidm/telegram-mcp-cli@latest login - 2
Add it with a single command in a terminal.
claude mcp add telegram \
-e TELEGRAM_API_ID=1234567 \
-e TELEGRAM_API_HASH=your-api-hash \
-e TELEGRAM_SESSION=your-session-string \
-- npx -y @thenavidm/telegram-mcp-cli@latest - 3
In Claude Code, type /mcp. Telegram should show as connected.
/mcp
- 1
Log in once in a terminal, with your API ID and hash.
Telegram asks for your phone number, the code it sends you and your two-step password if you have one. Put the session string it prints into TELEGRAM_SESSION below.
export TELEGRAM_API_ID=1234567
export TELEGRAM_API_HASH=your-api-hash
npx -y @thenavidm/telegram-mcp-cli@latest login - 2Download the extension
Download the Claude Desktop extension.
- 3
Double-click it, and Claude Desktop installs it.
- 1
Log in once in a terminal, with your API ID and hash.
Telegram asks for your phone number, the code it sends you and your two-step password if you have one. Put the session string it prints into TELEGRAM_SESSION below.
$env:TELEGRAM_API_ID = "1234567"
$env:TELEGRAM_API_HASH = "your-api-hash"
npx -y @thenavidm/telegram-mcp-cli@latest login - 2Download the extension
Download the Claude Desktop extension.
- 3
Double-click it, and Claude Desktop installs it.
- 1
Log in once in a terminal, with your API ID and hash.
Telegram asks for your phone number, the code it sends you and your two-step password if you have one. Put the session string it prints into TELEGRAM_SESSION below.
export TELEGRAM_API_ID=1234567
export TELEGRAM_API_HASH=your-api-hash
npx -y @thenavidm/telegram-mcp-cli@latest login - 2Download the extension
Download the Claude Desktop extension.
- 3
Double-click it, and Claude Desktop installs it.
- 1
Log in once in a terminal, with your API ID and hash.
Telegram asks for your phone number, the code it sends you and your two-step password if you have one. Put the session string it prints into TELEGRAM_SESSION below.
export TELEGRAM_API_ID=1234567
export TELEGRAM_API_HASH=your-api-hash
npx -y @thenavidm/telegram-mcp-cli@latest login - 2
Add it with a single command in a terminal.
codex mcp add telegram \
--env TELEGRAM_API_ID=1234567 \
--env TELEGRAM_API_HASH=your-api-hash \
--env TELEGRAM_SESSION=your-session-string \
-- npx -y @thenavidm/telegram-mcp-cli@latest - 3
Check that Codex lists it.
codex mcp list
- 1
Log in once in a terminal, with your API ID and hash.
Telegram asks for your phone number, the code it sends you and your two-step password if you have one. Put the session string it prints into TELEGRAM_SESSION below.
$env:TELEGRAM_API_ID = "1234567"
$env:TELEGRAM_API_HASH = "your-api-hash"
npx -y @thenavidm/telegram-mcp-cli@latest login - 2
Add it with a single command in a terminal.
codex mcp add telegram --env TELEGRAM_API_ID="1234567" --env TELEGRAM_API_HASH="your-api-hash" --env TELEGRAM_SESSION="your-session-string" -- npx -y @thenavidm/telegram-mcp-cli@latest - 3
Check that Codex lists it.
codex mcp list
- 1
Log in once in a terminal, with your API ID and hash.
Telegram asks for your phone number, the code it sends you and your two-step password if you have one. Put the session string it prints into TELEGRAM_SESSION below.
export TELEGRAM_API_ID=1234567
export TELEGRAM_API_HASH=your-api-hash
npx -y @thenavidm/telegram-mcp-cli@latest login - 2
Add it with a single command in a terminal.
codex mcp add telegram \
--env TELEGRAM_API_ID=1234567 \
--env TELEGRAM_API_HASH=your-api-hash \
--env TELEGRAM_SESSION=your-session-string \
-- npx -y @thenavidm/telegram-mcp-cli@latest - 3
Check that Codex lists it.
codex mcp list
- 1
Log in once in a terminal, with your API ID and hash.
Telegram asks for your phone number, the code it sends you and your two-step password if you have one. Put the session string it prints into TELEGRAM_SESSION below.
export TELEGRAM_API_ID=1234567
export TELEGRAM_API_HASH=your-api-hash
npx -y @thenavidm/telegram-mcp-cli@latest login - 2
Open Cursor's settings, go to the MCP tab, and click Add new global MCP server.
- 3
Add the server.
{
"mcpServers": {
"telegram": {
"command": "npx",
"args": ["-y", "@thenavidm/telegram-mcp-cli@latest"],
"env": {
"TELEGRAM_API_ID": "1234567",
"TELEGRAM_API_HASH": "your-api-hash",
"TELEGRAM_SESSION": "your-session-string"
}
}
}
} - 4
Open the MCP tab again. It should show 13 tools.
- 1
Log in once in a terminal, with your API ID and hash.
Telegram asks for your phone number, the code it sends you and your two-step password if you have one. Put the session string it prints into TELEGRAM_SESSION below.
$env:TELEGRAM_API_ID = "1234567"
$env:TELEGRAM_API_HASH = "your-api-hash"
npx -y @thenavidm/telegram-mcp-cli@latest login - 2
Open Cursor's settings, go to the MCP tab, and click Add new global MCP server.
- 3
Add the server.
{
"mcpServers": {
"telegram": {
"command": "npx",
"args": ["-y", "@thenavidm/telegram-mcp-cli@latest"],
"env": {
"TELEGRAM_API_ID": "1234567",
"TELEGRAM_API_HASH": "your-api-hash",
"TELEGRAM_SESSION": "your-session-string"
}
}
}
} - 4
Open the MCP tab again. It should show 13 tools.
- 1
Log in once in a terminal, with your API ID and hash.
Telegram asks for your phone number, the code it sends you and your two-step password if you have one. Put the session string it prints into TELEGRAM_SESSION below.
export TELEGRAM_API_ID=1234567
export TELEGRAM_API_HASH=your-api-hash
npx -y @thenavidm/telegram-mcp-cli@latest login - 2
Open Cursor's settings, go to the MCP tab, and click Add new global MCP server.
- 3
Add the server.
{
"mcpServers": {
"telegram": {
"command": "npx",
"args": ["-y", "@thenavidm/telegram-mcp-cli@latest"],
"env": {
"TELEGRAM_API_ID": "1234567",
"TELEGRAM_API_HASH": "your-api-hash",
"TELEGRAM_SESSION": "your-session-string"
}
}
}
} - 4
Open the MCP tab again. It should show 13 tools.
- 1
Log in once in a terminal, with your API ID and hash.
Telegram asks for your phone number, the code it sends you and your two-step password if you have one. Put the session string it prints into TELEGRAM_SESSION below.
export TELEGRAM_API_ID=1234567
export TELEGRAM_API_HASH=your-api-hash
npx -y @thenavidm/telegram-mcp-cli@latest login - 2
Open the Command Palette and run MCP: Open User Configuration.
- 3
Add the server to that mcp.json.
If the file already has servers, add only this one inside servers.
{
"servers": {
"telegram": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@thenavidm/telegram-mcp-cli@latest"],
"env": {
"TELEGRAM_API_ID": "1234567",
"TELEGRAM_API_HASH": "your-api-hash",
"TELEGRAM_SESSION": "your-session-string"
}
}
}
}
- 1
Log in once in a terminal, with your API ID and hash.
Telegram asks for your phone number, the code it sends you and your two-step password if you have one. Put the session string it prints into TELEGRAM_SESSION below.
$env:TELEGRAM_API_ID = "1234567"
$env:TELEGRAM_API_HASH = "your-api-hash"
npx -y @thenavidm/telegram-mcp-cli@latest login - 2
Open the Command Palette and run MCP: Open User Configuration.
- 3
Add the server to that mcp.json.
If the file already has servers, add only this one inside servers.
{
"servers": {
"telegram": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@thenavidm/telegram-mcp-cli@latest"],
"env": {
"TELEGRAM_API_ID": "1234567",
"TELEGRAM_API_HASH": "your-api-hash",
"TELEGRAM_SESSION": "your-session-string"
}
}
}
}
- 1
Log in once in a terminal, with your API ID and hash.
Telegram asks for your phone number, the code it sends you and your two-step password if you have one. Put the session string it prints into TELEGRAM_SESSION below.
export TELEGRAM_API_ID=1234567
export TELEGRAM_API_HASH=your-api-hash
npx -y @thenavidm/telegram-mcp-cli@latest login - 2
Open the Command Palette and run MCP: Open User Configuration.
- 3
Add the server to that mcp.json.
If the file already has servers, add only this one inside servers.
{
"servers": {
"telegram": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@thenavidm/telegram-mcp-cli@latest"],
"env": {
"TELEGRAM_API_ID": "1234567",
"TELEGRAM_API_HASH": "your-api-hash",
"TELEGRAM_SESSION": "your-session-string"
}
}
}
}
- 1
Log in once in a terminal, with your API ID and hash.
Telegram asks for your phone number, the code it sends you and your two-step password if you have one. Put the session string it prints into TELEGRAM_SESSION below.
export TELEGRAM_API_ID=1234567
export TELEGRAM_API_HASH=your-api-hash
npx -y @thenavidm/telegram-mcp-cli@latest login - 2
Add it with a single command in a terminal.
copilot mcp add telegram \
--env TELEGRAM_API_ID=1234567 \
--env TELEGRAM_API_HASH=your-api-hash \
--env TELEGRAM_SESSION=your-session-string \
-- npx -y @thenavidm/telegram-mcp-cli@latest - 3
Check that Copilot CLI has it.
copilot mcp get telegram
- 1
Log in once in a terminal, with your API ID and hash.
Telegram asks for your phone number, the code it sends you and your two-step password if you have one. Put the session string it prints into TELEGRAM_SESSION below.
$env:TELEGRAM_API_ID = "1234567"
$env:TELEGRAM_API_HASH = "your-api-hash"
npx -y @thenavidm/telegram-mcp-cli@latest login - 2
Add it with a single command in a terminal.
copilot mcp add telegram --env TELEGRAM_API_ID="1234567" --env TELEGRAM_API_HASH="your-api-hash" --env TELEGRAM_SESSION="your-session-string" -- npx -y @thenavidm/telegram-mcp-cli@latest - 3
Check that Copilot CLI has it.
copilot mcp get telegram
- 1
Log in once in a terminal, with your API ID and hash.
Telegram asks for your phone number, the code it sends you and your two-step password if you have one. Put the session string it prints into TELEGRAM_SESSION below.
export TELEGRAM_API_ID=1234567
export TELEGRAM_API_HASH=your-api-hash
npx -y @thenavidm/telegram-mcp-cli@latest login - 2
Add it with a single command in a terminal.
copilot mcp add telegram \
--env TELEGRAM_API_ID=1234567 \
--env TELEGRAM_API_HASH=your-api-hash \
--env TELEGRAM_SESSION=your-session-string \
-- npx -y @thenavidm/telegram-mcp-cli@latest - 3
Check that Copilot CLI has it.
copilot mcp get telegram
- 1
Log in once in a terminal, with your API ID and hash.
Telegram asks for your phone number, the code it sends you and your two-step password if you have one. Put the session string it prints into TELEGRAM_SESSION below.
export TELEGRAM_API_ID=1234567
export TELEGRAM_API_HASH=your-api-hash
npx -y @thenavidm/telegram-mcp-cli@latest login - 2
Open your Gemini CLI settings.
~/.gemini/settings.json - 3
Add the server to settings.json.
If the file already has servers, add only this one inside mcpServers.
{
"mcpServers": {
"telegram": {
"command": "npx",
"args": ["-y", "@thenavidm/telegram-mcp-cli@latest"],
"env": {
"TELEGRAM_API_ID": "1234567",
"TELEGRAM_API_HASH": "your-api-hash",
"TELEGRAM_SESSION": "your-session-string"
}
}
}
} - 4
Restart Gemini CLI and type /mcp to check it.
/mcp
- 1
Log in once in a terminal, with your API ID and hash.
Telegram asks for your phone number, the code it sends you and your two-step password if you have one. Put the session string it prints into TELEGRAM_SESSION below.
$env:TELEGRAM_API_ID = "1234567"
$env:TELEGRAM_API_HASH = "your-api-hash"
npx -y @thenavidm/telegram-mcp-cli@latest login - 2
Open your Gemini CLI settings.
%USERPROFILE%\.gemini\settings.json - 3
Add the server to settings.json.
If the file already has servers, add only this one inside mcpServers.
{
"mcpServers": {
"telegram": {
"command": "npx",
"args": ["-y", "@thenavidm/telegram-mcp-cli@latest"],
"env": {
"TELEGRAM_API_ID": "1234567",
"TELEGRAM_API_HASH": "your-api-hash",
"TELEGRAM_SESSION": "your-session-string"
}
}
}
} - 4
Restart Gemini CLI and type /mcp to check it.
/mcp
- 1
Log in once in a terminal, with your API ID and hash.
Telegram asks for your phone number, the code it sends you and your two-step password if you have one. Put the session string it prints into TELEGRAM_SESSION below.
export TELEGRAM_API_ID=1234567
export TELEGRAM_API_HASH=your-api-hash
npx -y @thenavidm/telegram-mcp-cli@latest login - 2
Open your Gemini CLI settings.
~/.gemini/settings.json - 3
Add the server to settings.json.
If the file already has servers, add only this one inside mcpServers.
{
"mcpServers": {
"telegram": {
"command": "npx",
"args": ["-y", "@thenavidm/telegram-mcp-cli@latest"],
"env": {
"TELEGRAM_API_ID": "1234567",
"TELEGRAM_API_HASH": "your-api-hash",
"TELEGRAM_SESSION": "your-session-string"
}
}
}
} - 4
Restart Gemini CLI and type /mcp to check it.
/mcp
- 1
Log in once in a terminal, with your API ID and hash.
Telegram asks for your phone number, the code it sends you and your two-step password if you have one. Put the session string it prints into TELEGRAM_SESSION below.
export TELEGRAM_API_ID=1234567
export TELEGRAM_API_HASH=your-api-hash
npx -y @thenavidm/telegram-mcp-cli@latest login - 2
Open your OpenCode config.
~/.config/opencode/opencode.json - 3
Add the server under mcp.
If the file already has servers, add only this one inside mcp.
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"telegram": {
"type": "local",
"command": ["npx", "-y", "@thenavidm/telegram-mcp-cli@latest"],
"enabled": true,
"environment": {
"TELEGRAM_API_ID": "1234567",
"TELEGRAM_API_HASH": "your-api-hash",
"TELEGRAM_SESSION": "your-session-string"
}
}
}
} - 4
Restart OpenCode.
- 1
Log in once in a terminal, with your API ID and hash.
Telegram asks for your phone number, the code it sends you and your two-step password if you have one. Put the session string it prints into TELEGRAM_SESSION below.
$env:TELEGRAM_API_ID = "1234567"
$env:TELEGRAM_API_HASH = "your-api-hash"
npx -y @thenavidm/telegram-mcp-cli@latest login - 2
Open your OpenCode config.
%USERPROFILE%\.config\opencode\opencode.json - 3
Add the server under mcp.
If the file already has servers, add only this one inside mcp.
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"telegram": {
"type": "local",
"command": ["npx", "-y", "@thenavidm/telegram-mcp-cli@latest"],
"enabled": true,
"environment": {
"TELEGRAM_API_ID": "1234567",
"TELEGRAM_API_HASH": "your-api-hash",
"TELEGRAM_SESSION": "your-session-string"
}
}
}
} - 4
Restart OpenCode.
- 1
Log in once in a terminal, with your API ID and hash.
Telegram asks for your phone number, the code it sends you and your two-step password if you have one. Put the session string it prints into TELEGRAM_SESSION below.
export TELEGRAM_API_ID=1234567
export TELEGRAM_API_HASH=your-api-hash
npx -y @thenavidm/telegram-mcp-cli@latest login - 2
Open your OpenCode config.
~/.config/opencode/opencode.json - 3
Add the server under mcp.
If the file already has servers, add only this one inside mcp.
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"telegram": {
"type": "local",
"command": ["npx", "-y", "@thenavidm/telegram-mcp-cli@latest"],
"enabled": true,
"environment": {
"TELEGRAM_API_ID": "1234567",
"TELEGRAM_API_HASH": "your-api-hash",
"TELEGRAM_SESSION": "your-session-string"
}
}
}
} - 4
Restart OpenCode.
- 1
Log in once in a terminal, with your API ID and hash.
Telegram asks for your phone number, the code it sends you and your two-step password if you have one. Put the session string it prints into TELEGRAM_SESSION below.
export TELEGRAM_API_ID=1234567
export TELEGRAM_API_HASH=your-api-hash
npx -y @thenavidm/telegram-mcp-cli@latest login - 2
Add it with a single command in a terminal.
openclaw mcp add telegram \
--command npx \
--arg -y \
--arg @thenavidm/telegram-mcp-cli@latest \
--env TELEGRAM_API_ID=1234567 \
--env TELEGRAM_API_HASH=your-api-hash \
--env TELEGRAM_SESSION=your-session-string - 3
Check that it starts and lists its tools.
openclaw mcp doctor telegram --probe
- 1
Log in once in a terminal, with your API ID and hash.
Telegram asks for your phone number, the code it sends you and your two-step password if you have one. Put the session string it prints into TELEGRAM_SESSION below.
$env:TELEGRAM_API_ID = "1234567"
$env:TELEGRAM_API_HASH = "your-api-hash"
npx -y @thenavidm/telegram-mcp-cli@latest login - 2
Add it with a single command in a terminal.
openclaw mcp add telegram --command npx --arg -y --arg @thenavidm/telegram-mcp-cli@latest --env TELEGRAM_API_ID="1234567" --env TELEGRAM_API_HASH="your-api-hash" --env TELEGRAM_SESSION="your-session-string" - 3
Check that it starts and lists its tools.
openclaw mcp doctor telegram --probe
- 1
Log in once in a terminal, with your API ID and hash.
Telegram asks for your phone number, the code it sends you and your two-step password if you have one. Put the session string it prints into TELEGRAM_SESSION below.
export TELEGRAM_API_ID=1234567
export TELEGRAM_API_HASH=your-api-hash
npx -y @thenavidm/telegram-mcp-cli@latest login - 2
Add it with a single command in a terminal.
openclaw mcp add telegram \
--command npx \
--arg -y \
--arg @thenavidm/telegram-mcp-cli@latest \
--env TELEGRAM_API_ID=1234567 \
--env TELEGRAM_API_HASH=your-api-hash \
--env TELEGRAM_SESSION=your-session-string - 3
Check that it starts and lists its tools.
openclaw mcp doctor telegram --probe
- 1
Log in once in a terminal, with your API ID and hash.
Telegram asks for your phone number, the code it sends you and your two-step password if you have one. Put the session string it prints into TELEGRAM_SESSION below.
export TELEGRAM_API_ID=1234567
export TELEGRAM_API_HASH=your-api-hash
npx -y @thenavidm/telegram-mcp-cli@latest login - 2
In the agent panel, click the … menu, then MCP Servers, Manage MCP Servers and View raw config.
- 3
Add the server to mcp_config.json.
If the file already has servers, add only this one inside mcpServers.
{
"mcpServers": {
"telegram": {
"command": "npx",
"args": ["-y", "@thenavidm/telegram-mcp-cli@latest"],
"env": {
"TELEGRAM_API_ID": "1234567",
"TELEGRAM_API_HASH": "your-api-hash",
"TELEGRAM_SESSION": "your-session-string"
}
}
}
}
- 1
Log in once in a terminal, with your API ID and hash.
Telegram asks for your phone number, the code it sends you and your two-step password if you have one. Put the session string it prints into TELEGRAM_SESSION below.
$env:TELEGRAM_API_ID = "1234567"
$env:TELEGRAM_API_HASH = "your-api-hash"
npx -y @thenavidm/telegram-mcp-cli@latest login - 2
In the agent panel, click the … menu, then MCP Servers, Manage MCP Servers and View raw config.
- 3
Add the server to mcp_config.json.
If the file already has servers, add only this one inside mcpServers.
{
"mcpServers": {
"telegram": {
"command": "npx",
"args": ["-y", "@thenavidm/telegram-mcp-cli@latest"],
"env": {
"TELEGRAM_API_ID": "1234567",
"TELEGRAM_API_HASH": "your-api-hash",
"TELEGRAM_SESSION": "your-session-string"
}
}
}
}
- 1
Log in once in a terminal, with your API ID and hash.
Telegram asks for your phone number, the code it sends you and your two-step password if you have one. Put the session string it prints into TELEGRAM_SESSION below.
export TELEGRAM_API_ID=1234567
export TELEGRAM_API_HASH=your-api-hash
npx -y @thenavidm/telegram-mcp-cli@latest login - 2
In the agent panel, click the … menu, then MCP Servers, Manage MCP Servers and View raw config.
- 3
Add the server to mcp_config.json.
If the file already has servers, add only this one inside mcpServers.
{
"mcpServers": {
"telegram": {
"command": "npx",
"args": ["-y", "@thenavidm/telegram-mcp-cli@latest"],
"env": {
"TELEGRAM_API_ID": "1234567",
"TELEGRAM_API_HASH": "your-api-hash",
"TELEGRAM_SESSION": "your-session-string"
}
}
}
}
- 1
Log in once in a terminal, with your API ID and hash.
Telegram asks for your phone number, the code it sends you and your two-step password if you have one. Put the session string it prints into TELEGRAM_SESSION below.
export TELEGRAM_API_ID=1234567
export TELEGRAM_API_HASH=your-api-hash
npx -y @thenavidm/telegram-mcp-cli@latest login - 2
Open your Hermes config.
~/.hermes/config.yaml - 3
Add the server under mcp_servers.
If the file already has mcp_servers, add only this one under it.
mcp_servers:
telegram:
command: "npx"
args: ["-y", "@thenavidm/telegram-mcp-cli@latest"]
env:
TELEGRAM_API_ID: "1234567"
TELEGRAM_API_HASH: "your-api-hash"
TELEGRAM_SESSION: "your-session-string"
- 1
Log in once in a terminal, with your API ID and hash.
Telegram asks for your phone number, the code it sends you and your two-step password if you have one. Put the session string it prints into TELEGRAM_SESSION below.
$env:TELEGRAM_API_ID = "1234567"
$env:TELEGRAM_API_HASH = "your-api-hash"
npx -y @thenavidm/telegram-mcp-cli@latest login - 2
Open your Hermes config.
%USERPROFILE%\.hermes\config.yaml - 3
Add the server under mcp_servers.
If the file already has mcp_servers, add only this one under it.
mcp_servers:
telegram:
command: "npx"
args: ["-y", "@thenavidm/telegram-mcp-cli@latest"]
env:
TELEGRAM_API_ID: "1234567"
TELEGRAM_API_HASH: "your-api-hash"
TELEGRAM_SESSION: "your-session-string"
- 1
Log in once in a terminal, with your API ID and hash.
Telegram asks for your phone number, the code it sends you and your two-step password if you have one. Put the session string it prints into TELEGRAM_SESSION below.
export TELEGRAM_API_ID=1234567
export TELEGRAM_API_HASH=your-api-hash
npx -y @thenavidm/telegram-mcp-cli@latest login - 2
Open your Hermes config.
~/.hermes/config.yaml - 3
Add the server under mcp_servers.
If the file already has mcp_servers, add only this one under it.
mcp_servers:
telegram:
command: "npx"
args: ["-y", "@thenavidm/telegram-mcp-cli@latest"]
env:
TELEGRAM_API_ID: "1234567"
TELEGRAM_API_HASH: "your-api-hash"
TELEGRAM_SESSION: "your-session-string"
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/telegram-mcp-cli@latest - 2
Give Claude Code the skill, so it knows every command.
The skill is the SKILL.md in the package. It tells Claude Code what each command does and which ones ask first.
mkdir -p ~/.claude/skills/telegram
cp "$(npm root -g)/@thenavidm/telegram-mcp-cli/SKILL.md" ~/.claude/skills/telegram/ - 3
Log in once.
export TELEGRAM_API_ID=1234567
export TELEGRAM_API_HASH=your-api-hash
telegram-cli login - 4
Save your Telegram details, so every new session has them.
echo 'export TELEGRAM_API_ID=1234567' >> ~/.zshrc
echo 'export TELEGRAM_API_HASH=your-api-hash' >> ~/.zshrc
echo 'export TELEGRAM_SESSION=your-session-string' >> ~/.zshrc - 5
Check your setup.
It names anything that's wrong and the fix.
telegram-cli doctor - 6
Ask Claude Code to use telegram-cli.
Running telegram-cli on its own lists every command, so Claude Code finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/telegram-mcp-cli@latest - 2
Give Claude Code the skill, so it knows every command.
The skill is the SKILL.md in the package. It tells Claude Code what each command does and which ones ask first.
New-Item -ItemType Directory -Force "$HOME\.claude\skills\telegram" | Out-Null
Copy-Item "$(npm root -g)\@thenavidm\telegram-mcp-cli\SKILL.md" "$HOME\.claude\skills\telegram\" - 3
Log in once.
$env:TELEGRAM_API_ID = "1234567"
$env:TELEGRAM_API_HASH = "your-api-hash"
telegram-cli login - 4
Save your Telegram details, so every new session has them.
setx TELEGRAM_API_ID "1234567"
setx TELEGRAM_API_HASH "your-api-hash"
setx TELEGRAM_SESSION "your-session-string" - 5
Check your setup.
It names anything that's wrong and the fix.
telegram-cli doctor - 6
Ask Claude Code to use telegram-cli.
Running telegram-cli on its own lists every command, so Claude Code finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/telegram-mcp-cli@latest - 2
Give Claude Code the skill, so it knows every command.
The skill is the SKILL.md in the package. It tells Claude Code what each command does and which ones ask first.
mkdir -p ~/.claude/skills/telegram
cp "$(npm root -g)/@thenavidm/telegram-mcp-cli/SKILL.md" ~/.claude/skills/telegram/ - 3
Log in once.
export TELEGRAM_API_ID=1234567
export TELEGRAM_API_HASH=your-api-hash
telegram-cli login - 4
Save your Telegram details, so every new session has them.
echo 'export TELEGRAM_API_ID=1234567' >> ~/.bashrc
echo 'export TELEGRAM_API_HASH=your-api-hash' >> ~/.bashrc
echo 'export TELEGRAM_SESSION=your-session-string' >> ~/.bashrc - 5
Check your setup.
It names anything that's wrong and the fix.
telegram-cli doctor - 6
Ask Claude Code to use telegram-cli.
Running telegram-cli on its own lists every command, so Claude Code finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/telegram-mcp-cli@latest - 2
Give Codex the skill, so it knows every command.
The skill is the SKILL.md in the package. It tells Codex what each command does and which ones ask first.
mkdir -p ~/.agents/skills/telegram
cp "$(npm root -g)/@thenavidm/telegram-mcp-cli/SKILL.md" ~/.agents/skills/telegram/ - 3
Log in once.
export TELEGRAM_API_ID=1234567
export TELEGRAM_API_HASH=your-api-hash
telegram-cli login - 4
Save your Telegram details, so every new session has them.
echo 'export TELEGRAM_API_ID=1234567' >> ~/.zshrc
echo 'export TELEGRAM_API_HASH=your-api-hash' >> ~/.zshrc
echo 'export TELEGRAM_SESSION=your-session-string' >> ~/.zshrc - 5
Check your setup.
It names anything that's wrong and the fix.
telegram-cli doctor - 6
Ask Codex to use telegram-cli.
Running telegram-cli on its own lists every command, so Codex finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/telegram-mcp-cli@latest - 2
Give Codex the skill, so it knows every command.
The skill is the SKILL.md in the package. It tells Codex what each command does and which ones ask first.
New-Item -ItemType Directory -Force "$HOME\.agents\skills\telegram" | Out-Null
Copy-Item "$(npm root -g)\@thenavidm\telegram-mcp-cli\SKILL.md" "$HOME\.agents\skills\telegram\" - 3
Log in once.
$env:TELEGRAM_API_ID = "1234567"
$env:TELEGRAM_API_HASH = "your-api-hash"
telegram-cli login - 4
Save your Telegram details, so every new session has them.
setx TELEGRAM_API_ID "1234567"
setx TELEGRAM_API_HASH "your-api-hash"
setx TELEGRAM_SESSION "your-session-string" - 5
Check your setup.
It names anything that's wrong and the fix.
telegram-cli doctor - 6
Ask Codex to use telegram-cli.
Running telegram-cli on its own lists every command, so Codex finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/telegram-mcp-cli@latest - 2
Give Codex the skill, so it knows every command.
The skill is the SKILL.md in the package. It tells Codex what each command does and which ones ask first.
mkdir -p ~/.agents/skills/telegram
cp "$(npm root -g)/@thenavidm/telegram-mcp-cli/SKILL.md" ~/.agents/skills/telegram/ - 3
Log in once.
export TELEGRAM_API_ID=1234567
export TELEGRAM_API_HASH=your-api-hash
telegram-cli login - 4
Save your Telegram details, so every new session has them.
echo 'export TELEGRAM_API_ID=1234567' >> ~/.bashrc
echo 'export TELEGRAM_API_HASH=your-api-hash' >> ~/.bashrc
echo 'export TELEGRAM_SESSION=your-session-string' >> ~/.bashrc - 5
Check your setup.
It names anything that's wrong and the fix.
telegram-cli doctor - 6
Ask Codex to use telegram-cli.
Running telegram-cli on its own lists every command, so Codex finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/telegram-mcp-cli@latest - 2
Log in once.
export TELEGRAM_API_ID=1234567
export TELEGRAM_API_HASH=your-api-hash
telegram-cli login - 3
Save your Telegram details, so every new session has them.
echo 'export TELEGRAM_API_ID=1234567' >> ~/.zshrc
echo 'export TELEGRAM_API_HASH=your-api-hash' >> ~/.zshrc
echo 'export TELEGRAM_SESSION=your-session-string' >> ~/.zshrc - 4
Check your setup.
It names anything that's wrong and the fix.
telegram-cli doctor - 5
Ask Cursor to use telegram-cli.
Running telegram-cli on its own lists every command, so Cursor finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/telegram-mcp-cli@latest - 2
Log in once.
$env:TELEGRAM_API_ID = "1234567"
$env:TELEGRAM_API_HASH = "your-api-hash"
telegram-cli login - 3
Save your Telegram details, so every new session has them.
setx TELEGRAM_API_ID "1234567"
setx TELEGRAM_API_HASH "your-api-hash"
setx TELEGRAM_SESSION "your-session-string" - 4
Check your setup.
It names anything that's wrong and the fix.
telegram-cli doctor - 5
Ask Cursor to use telegram-cli.
Running telegram-cli on its own lists every command, so Cursor finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/telegram-mcp-cli@latest - 2
Log in once.
export TELEGRAM_API_ID=1234567
export TELEGRAM_API_HASH=your-api-hash
telegram-cli login - 3
Save your Telegram details, so every new session has them.
echo 'export TELEGRAM_API_ID=1234567' >> ~/.bashrc
echo 'export TELEGRAM_API_HASH=your-api-hash' >> ~/.bashrc
echo 'export TELEGRAM_SESSION=your-session-string' >> ~/.bashrc - 4
Check your setup.
It names anything that's wrong and the fix.
telegram-cli doctor - 5
Ask Cursor to use telegram-cli.
Running telegram-cli on its own lists every command, so Cursor finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/telegram-mcp-cli@latest - 2
Log in once.
export TELEGRAM_API_ID=1234567
export TELEGRAM_API_HASH=your-api-hash
telegram-cli login - 3
Save your Telegram details, so every new session has them.
echo 'export TELEGRAM_API_ID=1234567' >> ~/.zshrc
echo 'export TELEGRAM_API_HASH=your-api-hash' >> ~/.zshrc
echo 'export TELEGRAM_SESSION=your-session-string' >> ~/.zshrc - 4
Check your setup.
It names anything that's wrong and the fix.
telegram-cli doctor - 5
Ask VS Code to use telegram-cli.
Running telegram-cli on its own lists every command, so VS Code finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/telegram-mcp-cli@latest - 2
Log in once.
$env:TELEGRAM_API_ID = "1234567"
$env:TELEGRAM_API_HASH = "your-api-hash"
telegram-cli login - 3
Save your Telegram details, so every new session has them.
setx TELEGRAM_API_ID "1234567"
setx TELEGRAM_API_HASH "your-api-hash"
setx TELEGRAM_SESSION "your-session-string" - 4
Check your setup.
It names anything that's wrong and the fix.
telegram-cli doctor - 5
Ask VS Code to use telegram-cli.
Running telegram-cli on its own lists every command, so VS Code finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/telegram-mcp-cli@latest - 2
Log in once.
export TELEGRAM_API_ID=1234567
export TELEGRAM_API_HASH=your-api-hash
telegram-cli login - 3
Save your Telegram details, so every new session has them.
echo 'export TELEGRAM_API_ID=1234567' >> ~/.bashrc
echo 'export TELEGRAM_API_HASH=your-api-hash' >> ~/.bashrc
echo 'export TELEGRAM_SESSION=your-session-string' >> ~/.bashrc - 4
Check your setup.
It names anything that's wrong and the fix.
telegram-cli doctor - 5
Ask VS Code to use telegram-cli.
Running telegram-cli on its own lists every command, so VS Code finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/telegram-mcp-cli@latest - 2
Give Copilot CLI the skill, so it knows every command.
The skill is the SKILL.md in the package. It tells Copilot CLI what each command does and which ones ask first.
mkdir -p ~/.copilot/skills/telegram
cp "$(npm root -g)/@thenavidm/telegram-mcp-cli/SKILL.md" ~/.copilot/skills/telegram/ - 3
Log in once.
export TELEGRAM_API_ID=1234567
export TELEGRAM_API_HASH=your-api-hash
telegram-cli login - 4
Save your Telegram details, so every new session has them.
echo 'export TELEGRAM_API_ID=1234567' >> ~/.zshrc
echo 'export TELEGRAM_API_HASH=your-api-hash' >> ~/.zshrc
echo 'export TELEGRAM_SESSION=your-session-string' >> ~/.zshrc - 5
Check your setup.
It names anything that's wrong and the fix.
telegram-cli doctor - 6
Ask Copilot CLI to use telegram-cli.
Running telegram-cli on its own lists every command, so Copilot CLI finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/telegram-mcp-cli@latest - 2
Give Copilot CLI the skill, so it knows every command.
The skill is the SKILL.md in the package. It tells Copilot CLI what each command does and which ones ask first.
New-Item -ItemType Directory -Force "$HOME\.copilot\skills\telegram" | Out-Null
Copy-Item "$(npm root -g)\@thenavidm\telegram-mcp-cli\SKILL.md" "$HOME\.copilot\skills\telegram\" - 3
Log in once.
$env:TELEGRAM_API_ID = "1234567"
$env:TELEGRAM_API_HASH = "your-api-hash"
telegram-cli login - 4
Save your Telegram details, so every new session has them.
setx TELEGRAM_API_ID "1234567"
setx TELEGRAM_API_HASH "your-api-hash"
setx TELEGRAM_SESSION "your-session-string" - 5
Check your setup.
It names anything that's wrong and the fix.
telegram-cli doctor - 6
Ask Copilot CLI to use telegram-cli.
Running telegram-cli on its own lists every command, so Copilot CLI finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/telegram-mcp-cli@latest - 2
Give Copilot CLI the skill, so it knows every command.
The skill is the SKILL.md in the package. It tells Copilot CLI what each command does and which ones ask first.
mkdir -p ~/.copilot/skills/telegram
cp "$(npm root -g)/@thenavidm/telegram-mcp-cli/SKILL.md" ~/.copilot/skills/telegram/ - 3
Log in once.
export TELEGRAM_API_ID=1234567
export TELEGRAM_API_HASH=your-api-hash
telegram-cli login - 4
Save your Telegram details, so every new session has them.
echo 'export TELEGRAM_API_ID=1234567' >> ~/.bashrc
echo 'export TELEGRAM_API_HASH=your-api-hash' >> ~/.bashrc
echo 'export TELEGRAM_SESSION=your-session-string' >> ~/.bashrc - 5
Check your setup.
It names anything that's wrong and the fix.
telegram-cli doctor - 6
Ask Copilot CLI to use telegram-cli.
Running telegram-cli on its own lists every command, so Copilot CLI finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/telegram-mcp-cli@latest - 2
Log in once.
export TELEGRAM_API_ID=1234567
export TELEGRAM_API_HASH=your-api-hash
telegram-cli login - 3
Save your Telegram details, so every new session has them.
echo 'export TELEGRAM_API_ID=1234567' >> ~/.zshrc
echo 'export TELEGRAM_API_HASH=your-api-hash' >> ~/.zshrc
echo 'export TELEGRAM_SESSION=your-session-string' >> ~/.zshrc - 4
Check your setup.
It names anything that's wrong and the fix.
telegram-cli doctor - 5
Ask Gemini CLI to use telegram-cli.
Running telegram-cli on its own lists every command, so Gemini CLI finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/telegram-mcp-cli@latest - 2
Log in once.
$env:TELEGRAM_API_ID = "1234567"
$env:TELEGRAM_API_HASH = "your-api-hash"
telegram-cli login - 3
Save your Telegram details, so every new session has them.
setx TELEGRAM_API_ID "1234567"
setx TELEGRAM_API_HASH "your-api-hash"
setx TELEGRAM_SESSION "your-session-string" - 4
Check your setup.
It names anything that's wrong and the fix.
telegram-cli doctor - 5
Ask Gemini CLI to use telegram-cli.
Running telegram-cli on its own lists every command, so Gemini CLI finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/telegram-mcp-cli@latest - 2
Log in once.
export TELEGRAM_API_ID=1234567
export TELEGRAM_API_HASH=your-api-hash
telegram-cli login - 3
Save your Telegram details, so every new session has them.
echo 'export TELEGRAM_API_ID=1234567' >> ~/.bashrc
echo 'export TELEGRAM_API_HASH=your-api-hash' >> ~/.bashrc
echo 'export TELEGRAM_SESSION=your-session-string' >> ~/.bashrc - 4
Check your setup.
It names anything that's wrong and the fix.
telegram-cli doctor - 5
Ask Gemini CLI to use telegram-cli.
Running telegram-cli on its own lists every command, so Gemini CLI finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/telegram-mcp-cli@latest - 2
Give OpenCode the skill, so it knows every command.
The skill is the SKILL.md in the package. It tells OpenCode what each command does and which ones ask first.
mkdir -p ~/.config/opencode/skills/telegram
cp "$(npm root -g)/@thenavidm/telegram-mcp-cli/SKILL.md" ~/.config/opencode/skills/telegram/ - 3
Log in once.
export TELEGRAM_API_ID=1234567
export TELEGRAM_API_HASH=your-api-hash
telegram-cli login - 4
Save your Telegram details, so every new session has them.
echo 'export TELEGRAM_API_ID=1234567' >> ~/.zshrc
echo 'export TELEGRAM_API_HASH=your-api-hash' >> ~/.zshrc
echo 'export TELEGRAM_SESSION=your-session-string' >> ~/.zshrc - 5
Check your setup.
It names anything that's wrong and the fix.
telegram-cli doctor - 6
Ask OpenCode to use telegram-cli.
Running telegram-cli on its own lists every command, so OpenCode finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/telegram-mcp-cli@latest - 2
Give OpenCode the skill, so it knows every command.
The skill is the SKILL.md in the package. It tells OpenCode what each command does and which ones ask first.
New-Item -ItemType Directory -Force "$HOME\.config\opencode\skills\telegram" | Out-Null
Copy-Item "$(npm root -g)\@thenavidm\telegram-mcp-cli\SKILL.md" "$HOME\.config\opencode\skills\telegram\" - 3
Log in once.
$env:TELEGRAM_API_ID = "1234567"
$env:TELEGRAM_API_HASH = "your-api-hash"
telegram-cli login - 4
Save your Telegram details, so every new session has them.
setx TELEGRAM_API_ID "1234567"
setx TELEGRAM_API_HASH "your-api-hash"
setx TELEGRAM_SESSION "your-session-string" - 5
Check your setup.
It names anything that's wrong and the fix.
telegram-cli doctor - 6
Ask OpenCode to use telegram-cli.
Running telegram-cli on its own lists every command, so OpenCode finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/telegram-mcp-cli@latest - 2
Give OpenCode the skill, so it knows every command.
The skill is the SKILL.md in the package. It tells OpenCode what each command does and which ones ask first.
mkdir -p ~/.config/opencode/skills/telegram
cp "$(npm root -g)/@thenavidm/telegram-mcp-cli/SKILL.md" ~/.config/opencode/skills/telegram/ - 3
Log in once.
export TELEGRAM_API_ID=1234567
export TELEGRAM_API_HASH=your-api-hash
telegram-cli login - 4
Save your Telegram details, so every new session has them.
echo 'export TELEGRAM_API_ID=1234567' >> ~/.bashrc
echo 'export TELEGRAM_API_HASH=your-api-hash' >> ~/.bashrc
echo 'export TELEGRAM_SESSION=your-session-string' >> ~/.bashrc - 5
Check your setup.
It names anything that's wrong and the fix.
telegram-cli doctor - 6
Ask OpenCode to use telegram-cli.
Running telegram-cli on its own lists every command, so OpenCode finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/telegram-mcp-cli@latest - 2
Give OpenClaw the skill, so it knows every command.
The skill is the SKILL.md in the package. It tells OpenClaw what each command does and which ones ask first.
mkdir -p ~/.openclaw/skills/telegram
cp "$(npm root -g)/@thenavidm/telegram-mcp-cli/SKILL.md" ~/.openclaw/skills/telegram/ - 3
Log in once.
export TELEGRAM_API_ID=1234567
export TELEGRAM_API_HASH=your-api-hash
telegram-cli login - 4
Save your Telegram details, so every new session has them.
echo 'export TELEGRAM_API_ID=1234567' >> ~/.zshrc
echo 'export TELEGRAM_API_HASH=your-api-hash' >> ~/.zshrc
echo 'export TELEGRAM_SESSION=your-session-string' >> ~/.zshrc - 5
Check your setup.
It names anything that's wrong and the fix.
telegram-cli doctor - 6
Ask OpenClaw to use telegram-cli.
Running telegram-cli on its own lists every command, so OpenClaw finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/telegram-mcp-cli@latest - 2
Give OpenClaw the skill, so it knows every command.
The skill is the SKILL.md in the package. It tells OpenClaw what each command does and which ones ask first.
New-Item -ItemType Directory -Force "$HOME\.openclaw\skills\telegram" | Out-Null
Copy-Item "$(npm root -g)\@thenavidm\telegram-mcp-cli\SKILL.md" "$HOME\.openclaw\skills\telegram\" - 3
Log in once.
$env:TELEGRAM_API_ID = "1234567"
$env:TELEGRAM_API_HASH = "your-api-hash"
telegram-cli login - 4
Save your Telegram details, so every new session has them.
setx TELEGRAM_API_ID "1234567"
setx TELEGRAM_API_HASH "your-api-hash"
setx TELEGRAM_SESSION "your-session-string" - 5
Check your setup.
It names anything that's wrong and the fix.
telegram-cli doctor - 6
Ask OpenClaw to use telegram-cli.
Running telegram-cli on its own lists every command, so OpenClaw finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/telegram-mcp-cli@latest - 2
Give OpenClaw the skill, so it knows every command.
The skill is the SKILL.md in the package. It tells OpenClaw what each command does and which ones ask first.
mkdir -p ~/.openclaw/skills/telegram
cp "$(npm root -g)/@thenavidm/telegram-mcp-cli/SKILL.md" ~/.openclaw/skills/telegram/ - 3
Log in once.
export TELEGRAM_API_ID=1234567
export TELEGRAM_API_HASH=your-api-hash
telegram-cli login - 4
Save your Telegram details, so every new session has them.
echo 'export TELEGRAM_API_ID=1234567' >> ~/.bashrc
echo 'export TELEGRAM_API_HASH=your-api-hash' >> ~/.bashrc
echo 'export TELEGRAM_SESSION=your-session-string' >> ~/.bashrc - 5
Check your setup.
It names anything that's wrong and the fix.
telegram-cli doctor - 6
Ask OpenClaw to use telegram-cli.
Running telegram-cli on its own lists every command, so OpenClaw finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/telegram-mcp-cli@latest - 2
Log in once.
export TELEGRAM_API_ID=1234567
export TELEGRAM_API_HASH=your-api-hash
telegram-cli login - 3
Save your Telegram details, so every new session has them.
echo 'export TELEGRAM_API_ID=1234567' >> ~/.zshrc
echo 'export TELEGRAM_API_HASH=your-api-hash' >> ~/.zshrc
echo 'export TELEGRAM_SESSION=your-session-string' >> ~/.zshrc - 4
Check your setup.
It names anything that's wrong and the fix.
telegram-cli doctor - 5
Ask Antigravity to use telegram-cli.
Running telegram-cli on its own lists every command, so Antigravity finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/telegram-mcp-cli@latest - 2
Log in once.
$env:TELEGRAM_API_ID = "1234567"
$env:TELEGRAM_API_HASH = "your-api-hash"
telegram-cli login - 3
Save your Telegram details, so every new session has them.
setx TELEGRAM_API_ID "1234567"
setx TELEGRAM_API_HASH "your-api-hash"
setx TELEGRAM_SESSION "your-session-string" - 4
Check your setup.
It names anything that's wrong and the fix.
telegram-cli doctor - 5
Ask Antigravity to use telegram-cli.
Running telegram-cli on its own lists every command, so Antigravity finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/telegram-mcp-cli@latest - 2
Log in once.
export TELEGRAM_API_ID=1234567
export TELEGRAM_API_HASH=your-api-hash
telegram-cli login - 3
Save your Telegram details, so every new session has them.
echo 'export TELEGRAM_API_ID=1234567' >> ~/.bashrc
echo 'export TELEGRAM_API_HASH=your-api-hash' >> ~/.bashrc
echo 'export TELEGRAM_SESSION=your-session-string' >> ~/.bashrc - 4
Check your setup.
It names anything that's wrong and the fix.
telegram-cli doctor - 5
Ask Antigravity to use telegram-cli.
Running telegram-cli on its own lists every command, so Antigravity finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/telegram-mcp-cli@latest - 2
Log in once.
export TELEGRAM_API_ID=1234567
export TELEGRAM_API_HASH=your-api-hash
telegram-cli login - 3
Save your Telegram details, so every new session has them.
echo 'export TELEGRAM_API_ID=1234567' >> ~/.zshrc
echo 'export TELEGRAM_API_HASH=your-api-hash' >> ~/.zshrc
echo 'export TELEGRAM_SESSION=your-session-string' >> ~/.zshrc - 4
Check your setup.
It names anything that's wrong and the fix.
telegram-cli doctor - 5
Ask Hermes to use telegram-cli.
Running telegram-cli on its own lists every command, so Hermes finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/telegram-mcp-cli@latest - 2
Log in once.
$env:TELEGRAM_API_ID = "1234567"
$env:TELEGRAM_API_HASH = "your-api-hash"
telegram-cli login - 3
Save your Telegram details, so every new session has them.
setx TELEGRAM_API_ID "1234567"
setx TELEGRAM_API_HASH "your-api-hash"
setx TELEGRAM_SESSION "your-session-string" - 4
Check your setup.
It names anything that's wrong and the fix.
telegram-cli doctor - 5
Ask Hermes to use telegram-cli.
Running telegram-cli on its own lists every command, so Hermes finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/telegram-mcp-cli@latest - 2
Log in once.
export TELEGRAM_API_ID=1234567
export TELEGRAM_API_HASH=your-api-hash
telegram-cli login - 3
Save your Telegram details, so every new session has them.
echo 'export TELEGRAM_API_ID=1234567' >> ~/.bashrc
echo 'export TELEGRAM_API_HASH=your-api-hash' >> ~/.bashrc
echo 'export TELEGRAM_SESSION=your-session-string' >> ~/.bashrc - 4
Check your setup.
It names anything that's wrong and the fix.
telegram-cli doctor - 5
Ask Hermes to use telegram-cli.
Running telegram-cli on its own lists every command, so Hermes finds the one it needs.
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/telegram-mcp-cli@latest - 2
Log in once.
export TELEGRAM_API_ID=1234567
export TELEGRAM_API_HASH=your-api-hash
telegram-cli login - 3
Save your Telegram details, so every new session has them.
echo 'export TELEGRAM_API_ID=1234567' >> ~/.zshrc
echo 'export TELEGRAM_API_HASH=your-api-hash' >> ~/.zshrc
echo 'export TELEGRAM_SESSION=your-session-string' >> ~/.zshrc - 4
Check your setup.
It names anything that's wrong and the fix.
telegram-cli doctor - 5
List every command, then try one.
telegram-cli
telegram-cli list-chats --limit 10
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/telegram-mcp-cli@latest - 2
Log in once.
$env:TELEGRAM_API_ID = "1234567"
$env:TELEGRAM_API_HASH = "your-api-hash"
telegram-cli login - 3
Save your Telegram details, so every new session has them.
setx TELEGRAM_API_ID "1234567"
setx TELEGRAM_API_HASH "your-api-hash"
setx TELEGRAM_SESSION "your-session-string" - 4
Check your setup.
It names anything that's wrong and the fix.
telegram-cli doctor - 5
List every command, then try one.
telegram-cli
telegram-cli list-chats --limit 10
- 1
Install the CLI. It needs Node 22 or newer.
npm install -g @thenavidm/telegram-mcp-cli@latest - 2
Log in once.
export TELEGRAM_API_ID=1234567
export TELEGRAM_API_HASH=your-api-hash
telegram-cli login - 3
Save your Telegram details, so every new session has them.
echo 'export TELEGRAM_API_ID=1234567' >> ~/.bashrc
echo 'export TELEGRAM_API_HASH=your-api-hash' >> ~/.bashrc
echo 'export TELEGRAM_SESSION=your-session-string' >> ~/.bashrc - 4
Check your setup.
It names anything that's wrong and the fix.
telegram-cli doctor - 5
List every command, then try one.
telegram-cli
telegram-cli list-chats --limit 10
Needs Node 22 or newer, an API ID and hash from my.telegram.org, and one login for your session string. Set it up.
It's free and open source. If it saves you time, star it on GitHub, so more people find it.
This free Telegram MCP server and CLI gives your AI real access to your real Telegram account: your chats, their history, search, contacts and media. It catches you up on your chats, searches years of history for the thing you half remember, and sends and forwards messages as you.
It's one install with two ways in. Claude, Codex, Cursor or any other MCP app calls its 13 tools for you, and the same tools work as a CLI that agents like Claude Code, Codex and OpenCode run, or that you type yourself.
In this guide, I'll show you:
- What the Telegram MCP server & CLI is, and what you can ask it
- How to install it and check that it works
- When to use the MCP server, and when the CLI
- Every tool, and how to keep your account safe
Every tool on this page comes from the server itself, and every cost was measured in Claude Code.
Key takeaways
What is the Telegram MCP server & CLI?
The Telegram MCP server & CLI is a free, open source program that lets AI agents read, search and answer your Telegram chats for you, in two ways. The MCP server is what an AI app like Claude, Codex or Cursor connects to, through MCP (Model Context Protocol), the open standard AI apps use to call outside tools.
You ask in plain language. Your AI picks the right tool, and the server makes the call to Telegram's own servers, logged in as you.
The CLI is the same program as commands. telegram-cli search --query "wifi password" runs the same code your AI runs when you ask for something someone sent you, whether an agent like Claude Code runs it or you do.
In an AI OS, the layer that connects your AI to your context, your data and your tools, a server like this is how your AI reaches Telegram. My guide to building an AI operating system names Telegram among the tools it reaches, and here's how I use AI myself.
What can you ask it?
Once it's set up, you ask the way you'd ask an assistant. These are real prompts it handles:
Try askingWhat did I miss in the group chats while I was asleep?
Search every chat for the wifi password someone sent me last year.
Find the last thing Sarah sent me about the invoice and reply that I'll look tonight.
Which conversations have unread messages, and which actually need an answer?
Save the PDF that Tom sent me this morning to my desktop.
Send myself a note in Saved Messages with these three links.
The second one shows why this is useful. Searching a decade of chats for something you half remember is what this does better than scrolling.
It works well next to my iMessage MCP server and Google Workspace MCP server, so your AI can search your Messages history and check your Gmail in the same chat. Every server I've made is on my MCP servers page.
For your messages, my free text summarizer and voice memo to text converter help too.
How to install the Telegram MCP server
Pick your app in the box at the top of this page. You log in once to get your session string, then paste three values into your app's config.
Windsurf, Zed and Cline take the same server, though they don't have a tab in the box yet. Follow the box's Cursor tab, and put its block here instead:
| App | Where the block goes |
|---|---|
| Windsurf | In the Cascade panel, open the Actions menu (…) and choose Open MCP config file, then paste the block. |
| Cline | Click the MCP Servers icon in the Cline panel, open the Configure tab, click Configure MCP Servers, and paste the block. |
| Zed | Go to Settings, then AI, then MCP Servers, and choose Add Server, then Add Local Server. Enter the block's command, arguments and variables, and Zed saves them under context_servers. |
Watch out: Use one session string per computer. If two computers or two servers use the same one at once, Telegram cancels it everywhere, and you log in again on each.
Set up Telegram
There are three values. The first two identify the app, and the third is you.
TELEGRAM_API_ID and TELEGRAM_API_HASH in your terminal.npx -y @thenavidm/telegram-mcp-cli login.TELEGRAM_SESSION in your app's config.The session string is your login, not a limited token. Anyone holding it can read every chat and send as you, so keep it in your app's config and out of anything you share. To revoke it, end the session in Telegram under Settings, then Devices.
Check that it works
Run the doctor. It checks the three values, connects, and says which account it's signed in as.
npx -y @thenavidm/telegram-mcp-cli doctorIf the server starts and then exits, the session string is usually wrong or was revoked. Run login again.
In Claude Code, /mcp also shows whether the Telegram server is connected. It's one of the Claude Code commands worth knowing.
Use the Telegram CLI
The CLI is the same 13 tools as commands. AI agents that run commands, like Claude Code, Codex and OpenCode, use it on their own, and you can type the same commands in a terminal or a script.
Every tool name becomes a command with dashes, so list_chats runs as telegram-cli list-chats.
npm install -g @thenavidm/telegram-mcp-cli
telegram-cli
telegram-cli list-chats --limit 10
telegram-cli search --query "invoice"
telegram-cli history --peer me --limit 5The bare telegram-cli lists every command, telegram-cli which <words> finds the command for a task, and telegram-cli <command> --help shows what a command takes. Deleting messages asks for --confirm first, and it's off entirely until you set TELEGRAM_ALLOW_DESTRUCTIVE=1.
telegram-cli install <app> adds the server to Claude Code, Codex, Claude Desktop, Cursor, VS Code or Gemini CLI, in each app's own format.
These are the flags you'll use most:
| Flag | What it does |
|---|---|
--json | Prints JSON |
--compact | Prints the JSON on one line |
--select a,b.c | Keeps only those fields, and a dotted path goes deeper |
--agent | Machine mode: compact JSON, no prompts, and it never confirms anything |
--confirm | Lets a write that asks first go ahead |
--dry-run | Shows what a write would do, without doing it |
A script can branch on the exit code:
| Exit code | What it means |
|---|---|
| 0 | It worked |
| 1 | Something unexpected went wrong |
| 2 | The command was typed wrong, or a write needed --confirm |
| 3 | It wasn't found |
| 4 | Telegram rejected the credentials |
| 5 | Telegram failed or couldn't be reached |
| 7 | You hit a rate limit, so wait and try again |
| 10 | Nothing is set up yet |
MCP server or CLI: which one?
Both are the same program with the same 13 tools. The difference is when your AI pays for them, in the tokens it reads.
- MCP server
- 2,400 tokens
- CLI
- Nothing
- MCP server
- 120 tokens
- CLI
- Nothing
- MCP server
- Nothing more, or in Claude Code the tools it picks
- CLI
- 2,300 tokens, once
- MCP server
- 48,000 tokens
- CLI
- 2,300 tokens
- MCP server
- Yes
- CLI
- No, there's no terminal there
- MCP server
- No
- CLI
- Yes
An app that loads every tool up front sends the full list with every message, whether you mention Telegram or not. Claude Code doesn't by default: its tool search sends only the tool names and the server's instructions, and loads a tool's full definition when your AI reaches for it.
The CLI costs nothing until Telegram comes up. Then your agent reads its skill file once and runs the commands it needs. With the skill added, Claude Code also lists its one-line description with every message, about 140 tokens.
When the whole conversation is about Telegram, the gap closes. Then the MCP server is the better experience, because you ask in plain language and your AI never has to look up a command.
How to spend less
In Claude Code, leave tool search on, which it is unless you've set ENABLE_TOOL_SEARCH=false.
Keep the default profile. TELEGRAM_TOOLS=full adds the other 61 tools to your AI's list and costs about 11,900 tokens a message in an app that loads every tool. The CLI reaches all 74 either way. TELEGRAM_READ_ONLY=1 cuts the list to the seven reading tools.
Or install the CLI and connect the server later, on the days it earns its place. Every tool stays in reach, and the standing cost drops to nothing.
Every number here was measured on October 5, 2026 in Claude Code 2.1.286 with Claude Opus 5.5. It's the same one-line prompt with and without the server connected, once with tool search off so every tool loads, and once with Claude Code's default. The skill was measured the same way, and other apps and models count tokens a little differently.
13 tools by default, 74 in reach
The server shows your AI 13 tools: the ones that get used, for reading, searching, sending and media. A model picks the right tool far more reliably from 13 than from 74, and the list costs much less.
The other 61, for contacts, groups, admin, folders, polls, reactions and privacy, are always there as CLI commands, where an unused one costs nothing. Set TELEGRAM_TOOLS=full to show them all to your AI too, or read for the reading tools only.
Every Telegram tool
The tables below list the 13 tools of the default profile, grouped the way the repo groups them. Of these, seven only read, and six send, edit, forward or mark as read.
Chats
list_chats- What it does
- Recent conversations, newest first.
- Kind
- Reads
get_chat- What it does
- Details of a single chat: name, kind, username, member count and description where the chat has them.
- Kind
- Reads
Messages
history- What it does
- Messages from one chat, newest first.
- Kind
- Reads
search- What it does
- Search message text, either inside one chat or across the whole account when no peer is given.
- Kind
- Reads
send- What it does
- Send a message to a chat.
- Kind
- Writes
edit- What it does
- Change the text of a message you sent.
- Kind
- Writes
delete- What it does
- Delete one or more messages.
- Kind
- Asks first
mark_read- What it does
- Clear the unread count on a chat.
- Kind
- Writes
forward- What it does
- Forward messages from one chat into another.
- Kind
- Writes
Media
download_media- What it does
- Save the photo, video, document or voice note attached to a message, and return the local path.
- Kind
- Reads
send_file- What it does
- Send a local file to a chat, with an optional caption.
- Kind
- Writes
Your account
whoami- What it does
- The Telegram account this session is signed in as.
- Kind
- Reads
resolve- What it does
- Turn a @username, phone number or numeric id into a chat you can act on.
- Kind
- Reads
Is the Telegram MCP server safe?
Writes work from the start, because answering your chats is the point. A message goes to a real person as you, so read what your AI is about to send.
delete can remove a message for everyone in the chat, so it's off until you set TELEGRAM_ALLOW_DESTRUCTIVE=1, and then it asks first. It's marked "Asks first" in the tool tables above.
When your AI calls one of them, the call needs a yes first. Where you use it decides who gives it:
- Claude Code (2.1.246 and later) asks you before every call, in every one of its permission modes.
- An app that can show forms asks you in a form.
- Any other app takes your AI's
confirm: trueas the yes, so tell your AI to check with you first. - An agent with no person to ask needs
TELEGRAM_CONFIRM=model, so itsconfirm: truecounts in every app. - In a terminal, you add
--confirmto the command.
If the answer is no, nothing reaches Telegram.
Make it read-only
Set TELEGRAM_READ_ONLY=1 and the write tools disappear from the tool list, so your AI can't see them, leaving seven.
Keep a log of every write
Set TELEGRAM_AUDIT_LOG to a file path. The server writes one line per attempted write, allowed or blocked, with what it was about to do and who approved it.
Watch out: Message text is written by other people and reaches your AI as input. The server strips hidden characters used to smuggle instructions, but treat what's in a chat as data, and give an agent you don't fully trust TELEGRAM_READ_ONLY=1.
Your data
There's no server of ours in between. The only calls go to Telegram's own servers, and there's no account to create and no tracking.
The session string lives wherever you put it, and the server never writes it to disk. Message text is held in memory for one call. Media goes where you ask, and the audit log is written only when you set TELEGRAM_AUDIT_LOG.
Several accounts
Each Telegram account needs its own login and its own server. Run the login once for each account, then add the server to your app a second time under another name, like telegram-work, with that account's session string.
No tool picks between accounts yet. A session set as TELEGRAM_SESSION_WORK is kept as a secret, but nothing uses it until one does.
Telegram MCP server settings
The first three are required. The rest are optional, as environment variables in your app's config.
TELEGRAM_API_ID- Default
- none
- What it does
- Holds the api_id from my.telegram.org
TELEGRAM_API_HASH- Default
- none
- What it does
- Holds the api_hash from the same page
TELEGRAM_SESSION- Default
- none
- What it does
- Holds the session string
loginprints
TELEGRAM_TOOLS- Default
core- What it does
- Picks the profile:
core,fullorread
TELEGRAM_READ_ONLY- Default
- off
- What it does
1never registers a write tool
TELEGRAM_ALLOW_DESTRUCTIVE- Default
- off
- What it does
1allowsdeleteat all
TELEGRAM_AUDIT_LOG- Default
- none
- What it does
- Names a file that gets one line per attempted write
TELEGRAM_SESSION_<LABEL>- Default
- none
- What it does
- Keeps another account's session, like
TELEGRAM_SESSION_WORK, but no tool picks between accounts yet
TELEGRAM_TIMEOUT- Default
30- What it does
- Seconds before an MTProto call gives up
TELEGRAM_CHANNEL_ALLOW- Default
~/.telegram-mcp/channel-allow.json- What it does
- The channel's allowlist
TELEGRAM_TOOLSETS- Default
all- What it does
- Turns on only the toolsets you name, comma separated
TELEGRAM_SURFACE- Default
full- What it does
searchlists three tools that find, describe and run the rest
TELEGRAM_TOOL_TIMEOUT_MS- Default
- none
- What it does
- Gives up on any tool after this many milliseconds
TELEGRAM_CONFIRM- Default
human- What it does
modellets your AI'sconfirm: trueapprove on its own, for an agent with no person to ask
TELEGRAM_HTTP_PORT- Default
8787- What it does
- Sets the port for
--http
TELEGRAM_HTTP_HOST- Default
127.0.0.1- What it does
- Sets the address for
--http, and any other needs a token
TELEGRAM_HTTP_TOKEN- Default
- none
- What it does
- Sets the bearer token every
--httprequest needs
TELEGRAM_HTTP_ALLOWED_ORIGINS- Default
- none
- What it does
- Lists other websites allowed to call
--http, comma separated
TELEGRAM_DEBUG- Default
- off
- What it does
1prints debug lines
Troubleshooting
Run the doctor first. It names the step that failed and the fix.
| What you see | What to do |
|---|---|
| Exit code 10, not configured | One of the three values is missing. The doctor names it |
| Exit code 4, auth | The session was revoked or cancelled. Run login again |
| Exit code 7, a flood wait | Telegram is rate limiting you. Wait the seconds it says, and don't retry in a loop |
| The session was cancelled on every computer | Two places used the same session string at once. Log in separately on each |
delete refuses | That's by design. Set TELEGRAM_ALLOW_DESTRUCTIVE=1 and pass --confirm |
If the server doesn't show up in your app at all, run the command your app runs, in a terminal, and read the error.
More free tools for staying in touch
Make a QR code that opens a chat, or tag the links you send so you can see which ones people open.
FAQs about the Telegram MCP server & CLI
Here are the questions people ask most about the Telegram MCP server and CLI.
The Telegram MCP server & CLI is a free, open source program that lets an AI app like Claude, Codex or Cursor read, search and answer your Telegram chats.
It has 13 tools for your chats, their history, search, sending and media, and the same tools run as a CLI that agents like Claude Code and Codex use, or that you type yourself.
An MCP server is a standard way to give an AI app real access to a tool, so it can act instead of guessing.
MCP stands for Model Context Protocol, and Claude, Codex, Cursor and many other AI apps speak it.
Every server I've made is on my MCP servers page.
The Telegram CLI is the same program as the Telegram MCP server, run as commands.
AI agents like Claude Code, Codex and OpenCode run them for you, and you can type them in a terminal or a script.
One npm package installs both.
Use the Telegram MCP server in an AI app with no terminal, like Claude Desktop's chat, and the CLI in a terminal, a script or a cron job.
In an AI app that can run commands, like Claude Code, Codex or Cursor, the CLI is the lighter choice, because it costs nothing until it runs.
Yes, the Telegram MCP server is free and open source under the MIT license, and Telegram's API is free.
The only thing you pay for is your own AI app.
No, it logs in as you, like a Telegram app on a new device, so it reads your real chats.
A bot only sees chats it was added to.
Telegram's terms allow user apps, and reading and answering your own chats is what this is built for.
Bulk or spammy sending through a user account is what gets accounts limited.
The same session string is running in two places at once, and Telegram cancels it everywhere.
Log in separately on each computer.
A model picks the right tool far more reliably from 13 than from 74, and the list costs less.
The other 61 are always there as CLI commands, and TELEGRAM_TOOLS=full shows them to your AI too.
The Telegram MCP server works with any app that speaks MCP.
That includes Claude Code, Claude Desktop, Codex, Cursor, VS Code, Windsurf, Zed, Cline, GitHub Copilot CLI, Gemini CLI, OpenCode, OpenClaw, Antigravity and Hermes.
I did.
I'm Navid Moazzez, and I made the Telegram MCP server & CLI as one of my free tools on navid.me.
You can read more about me.
The code is on GitHub under the MIT license, and the package is on npm.
More MCP servers & CLIs
Related free tools
Navid.me is reader-supported. When you buy through links on this site, I may earn an affiliate commission. Read the affiliate disclaimer.
On this page
The most actionable AI newsletter for founders
Every week, get proven AI strategies, curated tools, and step-by-step systems to grow your audience, create better content, and build a profitable creator business.
No fluff, no filler, no BS. Just five minutes each week that might level up your online business and life.
P.S. Sign up now to get free access to my ultimate AI tools guide for creators.
