home / mcp / telegram mcp server

Telegram MCP Server

MCP server to work with Telegram through MTProto

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "sparfenyuk-mcp-telegram": {
      "command": "uv",
      "args": [
        "run",
        "mcp-telegram",
        "--help"
      ],
      "env": {
        "TELEGRAM_API_ID": "YOUR_API_ID",
        "TELEGRAM_API_HASH": "YOUR_API_HASH"
      }
    }
  }
}

You can connect Claude Desktop to Telegram data through the Telegram MCP Server, enabling you to access your Telegram dialogs and messages in a controlled, read-only way via MCP. This bridge lets AI assistants interact with Telegram data while keeping you in control of what’s exposed.

How to use

Use this MCP server to access Telegram conversations and unread messages from Claude Desktop. You get read-only access to the list of dialogs and the unread messages in a chosen dialog. This setup is designed to be safe and compliant, focusing on enabling AI-assisted reading and summarization without modifying Telegram data.

How to install

Prerequisites ensure you have the tooling to install and run MCP servers.

uv tool install git+https://github.com/sparfenyuk/mcp-telegram

> If you have already installed the server, you can update it using `uv tool upgrade --reinstall` command.

> If you want to delete the server, use the `uv tool uninstall mcp-telegram` command.

Configuration

Configure the server to authenticate with Telegram and connect Claude Desktop.

Telegram API Configuration Before using the server, connect to the Telegram API by obtaining your API ID and hash from Telegram and signing in.

mcp-telegram sign-in --api-id <your-api-id> --api-hash <your-api-hash> --phone-number <your-phone-number> 

Enter the code you receive from Telegram to complete the sign-in. The password may be required if two-factor authentication is enabled.

Claude Desktop Configuration Configure Claude Desktop to recognize the Exa MCP server by adding a server entry to the Claude Desktop configuration file.

{
  "mcpServers": {
    "mcp-telegram": {
      "command": "mcp-server",
      "env": {
        "TELEGRAM_API_ID": "<your-api-id>",
        "TELEGRAM_API_HASH": "<your-api-hash>"
      }
    }
  }
}

Telegram Configuration Create your Telegram application to obtain API credentials. Log in with the developer account, create a new application, and note the API hash securely.

1) Go to API Development tools in Telegram
2) Create a new application and note the App title and Short name
3) Copy the API ID and API hash; keep the hash secret

Development

Development work is centered on adding tools and testing with the MCP inspector and CLI helpers.

Getting started 1) Clone the repository 2) Install dependencies 3) Run the server with help text.

uv sync

uv run mcp-telegram --help

Tools can be added by creating new tool classes and registering them. Restart the client to expose the new tool.

Debugging in terminal List all tools and invoke a specific one to verify behavior.

# List all available tools
uv run cli.py list-tools

# Run a concrete tool with arguments
uv run cli.py call-tool --name ListDialogs --arguments '{"unread": true}'

Inspector To debug with a visual UI, run the MCP inspector against the server.

npx @modelcontextprotocol/inspector uv run mcp-telegram

Troubleshooting

If Claude Desktop shows a connection error to the MCP server, verify the server configuration and environment. Common fixes include ensuring the correct command path and environment variables are set.

- Ensure the full path to the uv binary is used in the configuration
- Double-check the path to the local repository in the configuration

Notes and tips

This server currently provides read-only access to Telegram dialogs and unread messages. Media downloads, message drafting, and more advanced Telegram interactions are marked as future capabilities.

Available tools

NewTool

A placeholder example tool illustrating how new MCP tools are defined and registered within the server. Implement the tool logic in a class that inherits from ToolArgs and provide a tool_runner function.

new_tool

Async function that processes arguments for the new tool and returns content for the client.