Home / MCP / Telegram MCP Server
An MCP server enabling AI assistants to interact with Telegram via the user client API, with dialog listing, message retrieval, and background archival to SQLite.
Configuration
View docs{
"mcpServers": {
"telegram": {
"url": "http://localhost:8080/mcp"
}
}
}You can run a Telegram MCP Server that lets AI assistants, like Claude or Cursor, interact with your Telegram account using the user client API. It exposes tools to list dialogs, fetch messages, and manage background archival jobs, while storing archived messages in SQLite for efficient access and replay.
Connect your MCP client to the server at the provided endpoint and use the included tools to explore channels, fetch messages, and schedule or monitor archival jobs. The server handles authentication with Telegram and performs background synchronization to SQLite, keeping your message archive up to date while respecting rate limits.
Prerequisites include a supported Node.js runtime and an active Telegram account with Two-Step Verification enabled. You also need Telegram API credentials (api_id and api_hash) from an application you create on Telegram.
Step-by-step commands to set up and run the server.
# 1) Clone the project
git clone https://github.com/your-username/telegram-mcp-server.git
cd telegram-mcp-server
# 2) Install dependencies
npm install
# 3) Create and populate environment variables (example)
# TELEGRAM_API_ID=YOUR_API_ID
# TELEGRAM_API_HASH=YOUR_API_HASH
# TELEGRAM_PHONE_NUMBER=YOUR_PHONE_NUMBER_WITH_COUNTRY_CODE
export TELEGRAM_API_ID=YOUR_API_ID
export TELEGRAM_API_HASH=YOUR_API_HASH
export TELEGRAM_PHONE_NUMBER=YOUR_PHONE_NUMBER_WITH_COUNTRY_CODE
# 4) Start the MCP server
npm start
# 5) On first run, complete MTProto authentication promptsConfigure the MCP server and the client you use to connect to it. The server uses MTProto to access Telegram with your account, and the client must point to the server URL at http://localhost:8080/mcp.
{
"mcpServers": {
"telegram": {
"url": "http://localhost:8080/mcp",
"disabled": false,
"timeout": 30
}
}
}During the first run, you authenticate with Telegram. A persistent session file is saved to keep you logged in across restarts. Ensure file permissions allow the running user to read and write to the data directory, and keep your session file secure.
Background sync jobs are stored in a SQLite database and processed sequentially. You can schedule and monitor jobs to archive channels or dialogs into the local database.
Using the provided tools, you can start a new sync job or list current jobs to monitor progress and status.
If you encounter login prompts repeatedly, verify the session file exists and is writable by the running process. Restart the server after ensuring the session file is in place. If chat lists look stale, a fresh server boot will refresh channel data.
Ensure dependencies are installed with npm install and that you run commands from the correct working directory. If issues persist, check for missing modules or permission problems in the data directory.
The Telegram client library used by the MCP server is included in this project. You can use it directly for custom scripting or advanced interactions with Telegram.
Lists available dialogs/channels with an adjustable limit to help you identify conversations you want to inspect.
Searches dialogs by title or username to quickly locate a conversation.
Fetches recent messages from a channel or dialog by ID or username, with optional filters.
Schedules a background job to archive a specific dialog/channel into SQLite.
Displays current sync jobs, their progress, and statuses.