Telegram MCP Server

File-path tools (e.g., send_file, download_media, upload_file) are disabled by default for security. You must explicitly configure allowed roots.

Roots can be provided via:

1. Server CLI arguments (fallback).
2. MCP client Roots (takes precedence).

Security Rules:

• Paths must resolve to a real path inside an allowed root.
• Traversal, wildcard, shell-like, and null-byte patterns are rejected.
• Downloads default to <first_root>/downloads/.
• If a client provides an empty list of roots, it acts as a deny-all. To force fallback to CLI roots in this case, set TELEGRAM_ALLOW_SERVER_ROOTS_FALLBACK=1.

Usage Examples

Via CLI:

uv run main.py /data/telegram /tmp/telegram-mcp

Via MCP Client Configuration (JSON):

{
  "mcpServers": {
    "telegram-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/full/path/to/telegram-mcp",
        "run",
        "main.py",
        "/data/telegram",
        "/tmp/telegram-mcp"
      ],
      "env": {
        "TELEGRAM_API_ID": "your_api_id_here",
        "TELEGRAM_API_HASH": "your_api_hash_here",
        "TELEGRAM_SESSION_STRING": "your_session_string_here"
      }
    }
  }
}

To use the server with Claude Desktop or Cursor, add a configuration entry pointing to your local clone of the repository.

Configuration via Local Clone

{
  "mcpServers": {
    "telegram-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/full/path/to/telegram-mcp",
        "run",
        "main.py"
      ],
      "env": {
        "TELEGRAM_API_ID": "your_api_id_here",
        "TELEGRAM_API_HASH": "your_api_hash_here",
        "TELEGRAM_SESSION_STRING": "your_session_string_here"
      }
    }
  }
}

Configuration via Installed Package

If you installed the repository directly via pip install "git+..." into a virtual environment:

{
  "mcpServers": {
    "telegram-mcp": {
      "command": "/full/path/to/.venv/bin/telegram-mcp",
      "env": {
        "TELEGRAM_API_ID": "your_api_id_here",
        "TELEGRAM_API_HASH": "your_api_hash_here",
        "TELEGRAM_SESSION_STRING": "your_session_string_here"
      }
    }
  }
}

The runtime implements a strict security model for file-path tools to prevent path traversal and unauthorized access.

1. Root Validation

All file operations must occur within 'allowed roots'. These roots are determined by:

1. The MCP client's list_roots capability (preferred).
2. Recovered absolute paths from client validation errors (e.g., when clients send bare paths instead of file:// URIs).
3. Server-side CLI arguments (if fallback is enabled).

2. Path Resolution Logic

• Absolute Paths: Checked directly against allowed roots.
• Relative Paths: Resolved relative to the first available resolution root.
• Security Checks:
  • Path traversal (..) is strictly forbidden.
  • Wildcard/shell patterns are disallowed.
  • The resolved path must be within an allowed root.

3. Tool-Specific Constraints

Tools may enforce additional constraints:

• Extension Allowlists: Only specific file extensions (e.g., .txt, .md) may be allowed for certain tools.
• Size Limits: Files exceeding MAX_FILE_BYTES for a specific tool will be rejected.
• Permissions: Files must be readable (for read tools) or the parent directory must be writable (for write tools).

Route Telegram traffic through a proxy using TELEGRAM_PROXY_* environment variables. Supported types are socks5, socks4, http, and mtproxy.

Note: SOCKS and HTTP proxies require the python-socks package. Install it via:

uv sync --extra proxy
# or
pip install python-socks

SOCKS/HTTP Configuration

TELEGRAM_PROXY_TYPE=socks5
TELEGRAM_PROXY_HOST=127.0.0.1
TELEGRAM_PROXY_PORT=1080
TELEGRAM_PROXY_USERNAME=optional_user
TELEGRAM_PROXY_PASSWORD=optional_pass
TELEGRAM_PROXY_RDNS=true

MTProxy Configuration

TELEGRAM_PROXY_TYPE=mtproxy
TELEGRAM_PROXY_HOST=mtproxy.example
TELEGRAM_PROXY_PORT=443
TELEGRAM_PROXY_SECRET=ee0123456789abcdef...

Per-account Overrides

Use the _<LABEL> suffix to override global proxy settings for specific accounts (e.g., TELEGRAM_PROXY_TYPE_WORK).

TELEGRAM_PROXY_TYPE=socks5
TELEGRAM_PROXY_HOST=127.0.0.1
TELEGRAM_PROXY_PORT=1080

TELEGRAM_PROXY_TYPE_WORK=http
TELEGRAM_PROXY_HOST_WORK=proxy.work.example
TELEGRAM_PROXY_PORT_WORK=3128

The server requires several environment variables for authentication and tool access control. Copy .env.example to .env to get started.

Authentication (Single Account)

• TELEGRAM_API_ID: Your Telegram API ID from my.telegram.org/apps.
• TELEGRAM_API_HASH: Your Telegram API Hash.
• TELEGRAM_SESSION_STRING: The session string generated via the session_string_generator.py script.

Tool Access Control

You can restrict the tools exposed to the MCP client using TELEGRAM_EXPOSED_TOOLS:

• all (default): All tools are exposed.
• read-only: Only tools with readOnlyHint=True are exposed.
• read-only+<tool1>,<tool2>: Read-only tools plus specific write tools (e.g., read-only+send_message,reply_to_message).

Note: An unknown tool name in the allowlist will cause the server to abort startup.

TELEGRAM_API_ID=your_api_id_here
TELEGRAM_API_HASH=your_api_hash_here
TELEGRAM_SESSION_STRING=your_session_string_here
TELEGRAM_EXPOSED_TOOLS=read-only+send_message,reply_to_message