Claude Telegram MCP

NPM package for integrating Telegram with Claude Code via MCP (Model Context Protocol). Allows sending and receiving messages through a Telegram bot using an asynchronous message queue.

Features

• ✅ Two-way communication between Claude Code and Telegram
• ✅ Asynchronous message queue (FIFO)
• ✅ Persistent message storage (SQLite)
• ✅ Long polling without need for public IP
• ✅ Authorization by Telegram User ID
• ✅ Automatic MCP server registration
• ✅ CLI installer for setup

Installation

1. Install Package

npm install -g @s1lverain/claude-telegram-mcp

Or locally:

npm install @s1lverain/claude-telegram-mcp

2. Get Telegram Bot Token

1. Open @BotFather in Telegram
2. Send command /newbot
3. Follow instructions to create a bot
4. Save the received token (e.g.: 123456789:ABCdefGHIjklMNOpqrsTUVwxyz)

3. Get Telegram User ID

1. Open @userinfobot in Telegram
2. Bot will automatically show your User ID
3. Save the numeric ID (e.g.: 123456789)

4. Setup

Run the installer:

npx @s1lverain/claude-telegram-mcp install

Installer will request:

• Telegram Bot Token
• Telegram User ID

After successful setup, configuration will be saved in ~/.claude-telegram-mcp.json, and MCP server will be registered in Claude Code.

5. Test Connection

Check that everything works:

npx @s1lverain/claude-telegram-mcp test

This command will send a test message to your Telegram.

6. Restart Claude Code

Restart Claude Code to load the new MCP server.

Usage

After installation and restarting Claude Code, you can use the following tools:

Send Message to Telegram

Use the send_telegram_message tool with the message parameter

Claude Code will automatically send the message to your Telegram.

Get Messages from Telegram

Use the get_telegram_messages tool to get new messages

Claude Code will retrieve all unread messages from the queue.

Architecture

┌─────────────┐
│ Claude Code │
└──────┬──────┘
       │ MCP Protocol
       ▼
┌─────────────┐
│  MCP Server │
└──────┬──────┘
       │
       ▼
┌─────────────┐     ┌──────────────┐
│   Queue     │◄────┤  Telegram    │
│  (SQLite)   │     │     Bot      │
└─────────────┘     └──────────────┘

Components

• MCP Server (src/mcp/mcpServer.ts) - Model Context Protocol server
• Telegram Bot (src/telegram/telegramBot.ts) - Telegram Bot API client with polling
• Message Queue (src/queue/messageQueue.ts) - SQLite message queue
• Config Manager (src/config/config.ts) - Configuration management

Project Structure

.
├── src/
│   ├── config/       # Configuration
│   ├── mcp/          # MCP server
│   ├── telegram/     # Telegram bot
│   ├── queue/        # Message queue
│   └── index.ts      # Entry point
├── bin/
│   └── cli.js        # CLI installer
├── tests/            # Tests
└── README.md         # Documentation

Development

Install Dependencies

npm install

Build

npm run build

Testing

npm test

Run in Development Mode

npm run build
node dist/index.js

Troubleshooting

Installation Error: "gyp ERR! configure error" or better-sqlite3 Issues

If you get a compilation error for better-sqlite3 during dependency installation, this usually means issues with development tools.

Solution for macOS:

1. Install full Xcode from App Store (recommended):

   • Open App Store
   • Find and install Xcode
   • After installation, launch Xcode and accept the license
   • Install additional components when prompted

2. Or update Command Line Tools:

   sudo xcode-select --reset
   xcode-select --install

3. After installation, reinstall dependencies:

   rm -rf node_modules package-lock.json
   npm install

If problem persists:

Try using Node.js version 18 or 20 (instead of 22), which have precompiled binaries available:

nvm install 20
nvm use 20
npm install

Error: "Config file not found"

Run the installer:

npx @s1lverain/claude-telegram-mcp install

Error: "Invalid config file"

Delete the configuration file and run the installer again:

rm ~/.claude-telegram-mcp.json
npx @s1lverain/claude-telegram-mcp install

Bot Not Responding

1. Make sure you sent /start to the bot in Telegram
2. Check User ID correctness:

   npx @s1lverain/claude-telegram-mcp test

3. Check bot token in @BotFather

MCP Server Not Appearing in Claude Code

1. Check MCP configuration file:

   cat ~/.cursor/mcp.json

2. Make sure server is registered:

   {
     "mcpServers": {
       "claude-telegram-mcp": {
         "command": "node",
         "args": ["/path/to/dist/index.js"]
       }
     }
   }

3. Restart Claude Code

Messages Not Delivered

1. Check error logs
2. Make sure bot is running and polling is active
3. Check message queue:
   • Database file: ~/.claude-telegram-mcp-queue.db
   • Can use SQLite client to view

Permission Issues

Make sure the application has write permissions to home directory:

ls -la ~/.claude-telegram-mcp.json
ls -la ~/.claude-telegram-mcp-queue.db

License

MIT

Support

If you encounter issues, create an issue in the project repository.