Telegram MCP Server
# telegram-mcp
## Requirements
- Python Project Manager, [UV](https://docs.astral.sh/uv/getting-started/installation/)
- [MCP Client](https://modelcontextprotocol.io/clients)
## Usage
1. install dependencies
```
pip3 install uv
uv venv
source .venv/bin/activate
uv sync
```
2. edit .env file with your telegram api id and hash ([My Telegram](https://my.telegram.org)), don't share with others.
3. start the http-server
`uv run http-server/http-server.py`
4. install the MCP Server
`uv run mcp install mcp-server/mcp-server.py`
## Available Functions
The MCP Server provides the following functions:
- `get_unread_entities`: Get entities which have unread messages in them
- `get_unread_messages(id)`: Get all unread messages from a given entity id
- `get_messages(id, count)`: Get messages limited by a count from an entity
- `get_entities`: Get all entities in the current session
- `get_entity_by_id(id)`: Get an entity from the current session
- `send_message(entity_id, content, reply_to_message_id)`: Send a message to an entity with optional markup and reply
## Common Issues & How to Fix
- Claude can't run MCP server >> Install uv with brew : `brew install uv`
- Can't create new app in Telegram >> Disconnect VPN and retry
## License
[MIT](https://choosealicense.com/licenses/mit/)
TDQS
Scored across 6 tools
Most tools have distinct purposes, but there is some overlap between get_entities and get_unread_entities, as both retrieve entities, which could cause confusion about which to use. However, the descriptions clarify that one gets all entities and the other gets only those with unread messages, mitigating ambiguity.
All tool names follow a consistent verb_noun pattern with snake_case, such as get_entities, send_message, and get_unread_messages. There are no deviations in naming conventions, making the set predictable and easy to understand.
With 6 tools, this server is well-scoped for managing Telegram sessions, covering key operations like retrieving entities, messages, and sending messages. The count is appropriate, avoiding bloat while providing essential functionality.
The toolset covers core messaging workflows, including reading and sending messages, but lacks operations for updating or deleting messages, which might be expected in a messaging domain. However, the provided tools handle the primary use cases effectively.