tg-mcp
MCP server for a personal Telegram account. Read, search, download media, and sendmessages or files, from any MCP client.
Credentials stay on the machine in ~/.tg/ and are never returned by any tool.
Setup on a new machine
Needs uv and nothing else. Python, dependencies and thepackage are all fetched on demand.
1. Sign in (once per machine, interactive because Telegram sends a code):
uvx --from git+https://github.com/Abdk4Moura/tg-mcp tg-mcp-login
It prompts for api_id / api_hash from https://my.telegram.org (API developmenttools), then your phone number, then the code Telegram sends to the app. It writes~/.tg/credentials.json and ~/.tg/session.session, both mode 600, and prints yourrecent chats with their ids.
2. Register the server:
claude mcp add telegram -- uvx --from git+https://github.com/Abdk4Moura/tg-mcp tg-mcp
That is the whole setup. claude mcp list should show telegram ✔ Connected.
Setting it up for other agents
Every MCP client needs the same two things. Whatever the config format, this is all it is:
| command | uvx |
| args | --from, git+https://github.com/Abdk4Moura/tg-mcp, tg-mcp |
The sign-in is per machine, not per agent. Run tg-mcp-login once and every agent onthat machine shares ~/.tg/. Adding a second or third client is config only.
Claude Code
claude mcp add telegram -- uvx --from git+https://github.com/Abdk4Moura/tg-mcp tg-mcp
Add --scope user to make it available in every project rather than just the current one.
Claude Desktop, Cursor, Windsurf, Continue, and most others
These share the same mcpServers block. Add:
{
"mcpServers": {
"telegram": {
"command": "uvx",
"args": ["--from", "git+https://github.com/Abdk4Moura/tg-mcp", "tg-mcp"]
}
}
}
to the client's config file:
| Client | File |
|---|---|
| Claude Desktop (macOS) | ~/Library/Application Support/Claude/claude_desktop_config.json |
| Claude Desktop (Windows) | %APPDATA%\Claude\claude_desktop_config.json |
| Cursor | ~/.cursor/mcp.json, or .cursor/mcp.json for one project |
| Windsurf | ~/.codeium/windsurf/mcp_config.json |
| Continue | ~/.continue/config.json |
Restart the client afterwards. Most only read MCP config at startup.
Anything else
Clients such as opencode, Codex and Zed use their own config shapes rather than themcpServers block above. Check that client's own MCP documentation, and give it the samecommand and args from the table at the top of this section.
If uvx is not on PATH
Some clients launch with a minimal environment and will not find uvx. Use its absolutepath as the command (which uvx to find it, commonly ~/.local/bin/uvx).
Tools
| Tool | What it does |
|---|---|
tg_whoami |
Which account is signed in |
tg_list_chats |
Recent chats with their numeric ids |
tg_read_chat |
Read messages; peer takes an id, @username, or me for Saved Messages; optional since / until as YYYY-MM-DD |
tg_search |
Search message text across all chats or within one peer |
tg_download_media |
Fetch a message's attachment to disk |
tg_send_message |
Sends text. Real, immediate, not recallable by this server |
tg_send_file |
Sends a file with an optional caption |
Sessions
Each machine that runs tg-mcp-login creates its own Telegram session, listedseparately under Settings → Devices and revocable on its own.
Copying session.session between machines also works, but both then share one sessionidentity: revoking it logs out both, and a login from a very different IP can tripTelegram's security checks. Prefer a fresh login per machine.
That file is full account access. Anyone holding it can read and send as you.
Configuration
| Variable | Default | Purpose |
|---|---|---|
TG_DIR |
~/.tg |
Where credentials.json and session.session live |
TG_DOWNLOAD_DIR |
$TG_DIR/downloads |
Where tg_download_media writes |
Local development
uv run --directory /path/to/tg-mcp tg-mcp
