guangxiangdebizi/telegram-mcp

✨ Features

🚀 Installation

Option 1: NPM Package (Recommended)

# Install the package
npm install @xingyuchen/telegram-mcp

# Or using yarn
yarn add @xingyuchen/telegram-mcp

Option 2: From Source

# Clone the repository
git clone https://github.com/guangxiangdebizi/telegram-mcp.git
cd telegram-mcp

# Install dependencies
npm install

# Build the project
npm run build

📋 Usage

🔧 Setup Your Telegram Bot

First time? You'll need a Telegram Bot Token:

1. 💬 Message @BotFather on Telegram
2. 🤖 Send /newbot command
3. 📝 Follow the instructions to create your bot
4. 🔑 Copy the bot token provided by BotFather
5. ✅ Use this token in the MCP tool calls

🚀 Deployment Options

npm start

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

npm run sse

{
  "mcpServers": {
    "telegram-mcp": {
      "type": "sse",
      "url": "http://localhost:3100/sse",
      "timeout": 600
    }
  }
}

🛠️ Available Tools

📤 send_message

📝 Send rich text messages with formatting support

🖼️ send_photo

📸 Share images with captions and formatting

📎 send_document

📄 Upload files and documents with custom names

🎥 send_video

🎬 Send video content with metadata and streaming

↗️ forward_message

🔄 Forward messages between different chats

🗑️ delete_message

❌ Remove messages from chats

ℹ️ get_chat

📊 Retrieve detailed chat information and permissions

🔧 Development

📁 Project Structure

📦 telegram-mcp/
├── 📂 src/
│   ├── 📄 index.ts          # 🚀 MCP server entry point
│   └── 📂 tools/           # 🛠️ Business tool modules
│       ├── 📄 sendMessage.ts    # 💬 Text messaging
│       ├── 📄 sendPhoto.ts      # 🖼️ Photo sharing
│       ├── 📄 sendDocument.ts   # 📎 Document upload
│       ├── 📄 sendVideo.ts      # 🎥 Video sharing
│       ├── 📄 getChat.ts        # ℹ️ Chat information
│       ├── 📄 forwardMessage.ts # ↗️ Message forwarding
│       └── 📄 deleteMessage.ts  # 🗑️ Message deletion
├── 📂 examples/
│   ├── 📄 claude-config.json    # ⚙️ Claude configuration
│   └── 📄 usage-examples.md     # 💡 Usage examples
├── 📄 package.json
├── 📄 tsconfig.json
└── 📄 README.md

🔨 Adding New Tools

1. Create a new tool file in src/tools/
2. Follow the existing tool pattern:

   export const yourTool = {
     name: "your_tool_name",
     description: "Tool description",
     parameters: { /* JSON Schema */ },
     async run(args: any) { /* Implementation */ }
   };
   

3. Import and register in src/index.ts
4. Add to both ListToolsRequestSchema and CallToolRequestSchema handlers

🚀 Development Scripts

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

🗺️ Roadmap

See for the complete feature roadmap and implementation priorities.

📄 License

👤 Author