Telegram MCP Server

This is a Model Context Protocol (MCP) server for Telegram.

With this you can search your personal Telegram messages, search your contacts, and send messages to either individuals or groups.

It connects to your personal Telegram account directly via the Telegram API (using the Telethon library). All your messages are stored locally in a SQLite database and only sent to an LLM (such as Claude) when the agent accesses them through tools (which you control).

Installation

Prerequisites

Python 3.6+
Anthropic Claude Desktop app (or Cursor)

Steps

Clone this repository
```
git clone https://github.com/Muhammad18557/telegram-mcp.git
cd telegram-mcp
```
Create a Python virtual environment and activate it:
```
python3 -m venv myenv
source myenv/bin/activate
```
Install dependencies:
```
pip install -r requirements.txt
```
This is the environment that can be used both for running the Telegram bridge and the MCP server.
Get your Telegram API credentials
- Go to https://my.telegram.org/auth
- Log in and go to "API development tools"
- Create a new application
- Note your API ID and API hash
Run the Telegram bridge

Navigate to the telegram-bridge directory:
```
cd telegram-bridge
```
Set up your API credentials as environment variables either by exporting them:
```
export TELEGRAM_API_ID=your_api_id
export TELEGRAM_API_HASH=your_api_hash
```
Or by creating a .env file based on the provided .env.example:
```
cp .env.example .env
nano .env  # or use your preferred text editor
```
Then update the values in the .env file:
```
TELEGRAM_API_ID=your_api_id
TELEGRAM_API_HASH=your_api_hash
```
Run the Python application:
```
python main.py
```
The first time you run it, you will be prompted to enter your phone number and the verification code sent to your Telegram account.

Connect to the MCP server

First, update the run_telegram_server.sh script with your absolute repository path:

# Open the script in your preferred editor
nano run_telegram_server.sh

# Update line 4 with your absolute path to the repository
# Change this:
BASE_DIR="/Users/muhammadabdullah/Desktop/mcp/telegram-mcp"
# To your actual BASE_DIR path (get it by running `pwd` in the telegram-mcp directory)

Then, configure the MCP server by creating a JSON configuration file with the following format. Use the BASE_DIR from above.

{
  "mcpServers": {
    "telegram": {
      "command": "/bin/bash",
      "args": [
        "{{BASE_DIR}}/run_telegram_server.sh"
      ]
    }
  }
}

For Claude, save this as claude_desktop_config.json in your Claude Desktop configuration directory at:

~/Library/Application\ Support/Claude/claude_desktop_config.json

For Cursor, save this as mcp.json in your Cursor configuration directory at:

~/.cursor/mcp.json

Restart Claude Desktop / Cursor

Open Claude Desktop and you should now see Telegram as an available integration.

Or restart Cursor.

Architecture Overview

This application consists of two main components:

Python Telegram Bridge (telegram-bridge/): A Python application that connects to Telegram's API, handles authentication, and stores message history in SQLite. It serves as the bridge between Telegram and the MCP server. Can real-time sync for latest messages. The bridge uses a modular architecture with:
- api/: Client and models for the Telegram API interface
- database/: SQLAlchemy ORM models and repositories for data access
- server/: FastAPI server for exposing bridge functionality
- service.py: Core service logic connecting components
Python MCP Server (telegram-mcp-server/): A Python server implementing the Model Context Protocol (MCP), which provides standardized tools for Claude to interact with Telegram data and send/receive messages. The MCP server now follows a modular package structure:
- telegram/models.py: Data classes for messages, chats, and contacts
- telegram/database.py: Database operations using SQLAlchemy ORM
- telegram/api.py: API client for Telegram Bridge
- telegram/display.py: Formatting for message and chat output

Data Storage

All message history is stored in a SQLite database within the telegram-bridge/store/ directory
The database maintains tables for chats and messages managed through SQLAlchemy ORM
Messages are indexed for efficient searching and retrieval
All database access is through SQLAlchemy for type safety and query building

Usage

Once connected, you can interact with your Telegram contacts through Claude, leveraging Claude's AI capabilities in your Telegram conversations.

MCP Tools

Claude can access the following tools to interact with Telegram:

search_contacts: Search for contacts by name or username
list_messages: Retrieve messages with optional filters and context
list_chats: List available chats with metadata
get_chat: Get information about a specific chat
get_direct_chat_by_contact: Find a direct chat with a specific contact
get_contact_chats: List all chats involving a specific contact
get_last_interaction: Get the most recent message with a contact
get_message_context: Retrieve context around a specific message
send_message: Send a Telegram message to a specified username or chat ID

Technical Details

Claude sends requests to the Python MCP server
The MCP server queries the Telegram bridge or directly the SQLite database
The bridge accesses the Telegram API and keeps the SQLite database up to date
Data flows back through the chain to Claude
When sending messages, the request flows from Claude through the MCP server to the Telegram bridge and to Telegram

Troubleshooting

Make sure both the Telegram bridge and the Python server are running for the integration to work properly.

Authentication Issues

Session expired: If your session expires, you might need to re-authenticate. Delete the telegram-bridge/store/telegram_session.session file and restart the bridge.
Two-factor authentication: If you have 2FA enabled on your Telegram account, you'll be prompted for your password during authentication.
No Messages Loading: After initial authentication, it can take several minutes for your message history to load, especially if you have many chats.

For additional Claude Desktop integration troubleshooting, see the MCP documentation.

Next Steps

This project is actively being developed. Future planned features include:

Rich Media Support: Handle and display photos, videos, and other media types
Message Threading: Better visualization of conversation threads
Message Editing: Support for editing sent messages
Web UI: A simple web interface for configuration and monitoring
Expanded Search: More advanced search capabilities for finding specific messages or running analysis on say unread chats
Improved Security: Enhanced authentication and encryption for local data

If you'd like to contribute to any of these features or suggest new ones, please check out our CONTRIBUTING.md guide.