Telegram MCP Server Ff8

🚀 Telegram MCP Server

A powerful Telegram integration server that offers various tools for managing contacts, sending messages, and retrieving channel information via MCP (Multi-Client Protocol).

✨ Features

• Contact Management

  • Retrieve the contact list.
  • Search for contacts.
  • View recent interactions.

• Messaging Functions

  • Send messages to contacts by name or phone number.
  • Filter chat history by date range.
  • View recent interactions.

• Channel Functions

  • Get channel posts.
  • Search for channels.
  • View channel information.
  • Filter posts by date range.

📋 Prerequisites

• Python 3.8 or higher.
• Node.js 14 or higher (for npx installation).
• Telegram API credentials (api_id and api_hash).
• A Telegram account.

📦 Installation

1. Clone the repository:

git clone https://github.com/yourusername/telegram-MCP-server.git
cd telegram-MCP-server

2. Install the required dependencies:

uv venv .venv  # Create a virtual environment
source .venv/bin/activate  # Activate (Linux/macOS)
.\venv\Scripts\activate  # Activate (Windows)
uv pip install

3. Create a .env file in the project root directory and enter your Telegram credentials:

TG_API_ID=your_api_id
TG_API_HASH=your_api_hash
phone=your_phone_number  # Format: +1234567890

💻 Integration with Cursor/Claude Desktop

Copy the following JSON and replace the corresponding {{PATH}} values:

{
  "mcpServers": {
    "whatsapp": {
      "command": "{{PATH_TO_UV}}", // Run `which uv` and place the output here
      "args": [
        "--directory",
        "{{PATH_TO_SRC}}/whatsapp-mcp/whatsapp-mcp-server", // Run `pwd` in the repo, enter the output and append "/whatsapp-mcp-server"
        "run",
        "main.py"
      ]
    }
  }
}

For Claude, save this file as claude_desktop_config.json at:

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

For Cursor, save this file as mcp.json at:

~/.cursor/mcp.json

📚 Documentation

get_contacts()

Returns a list of all Telegram contacts, including names, phone numbers, and usernames.

send_message_by_identifier(identifier: str, message: str)

Sends a message to a specific contact by name or phone number.

• identifier: The name or phone number of the contact.
• message: The text message to send.

get_last_interaction(identifier: str)

Returns the most recent message with a specific contact.

• identifier: The name or phone number of the contact.

get_chat_history(identifier: str, start_date: str = None, end_date: str = None, limit: int = 20)

Retrieves the chat history with a contact within a specified date range.

• identifier: The name or phone number of the contact.
• start_date: Optional start date (YYYY-MM-DD).
• end_date: Optional end date (YYYY-MM-DD).
• limit: Optional limit on the number of results.

get_posts_by_hashtag(hashtag: str, limit: int = 20)

Retrieves posts by a specified hashtag.

• hashtag: The hashtag to search for.
• limit: Optional limit on the number of results.

🔧 Error Handling

handle_errors()

Handles potential errors.

⚠️ Security Considerations

• Ensure the security of your credentials and avoid disclosure.
• Avoid using this tool on public networks.

🤝 Contribution Guidelines

How to Contribute

1. Fork the repository.
2. Create a feature branch.
3. Commit your changes.
4. Push to the branch.
5. Create a Pull Request.

Contributors

• [Your Name] - [Your Role]

📄 License

[Insert license content]