tg-mcp

MCP server for a personal Telegram account. Read, search, download media, and send messages 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 the package 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 development tools), 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 your recent 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

The sign-in is per machine, not per agent. Run tg-mcp-login once and every agent on that machine shares ~/.tg/. Adding a second or third client is config only.

There is no single config format across MCP clients, so this package ships an installer that writes each one in its own shape:

uvx --from git+https://github.com/Abdk4Moura/tg-mcp tg-mcp-install

It configures every supported client it finds and leaves the rest alone. --list shows what it detected, --dry-run prints the changes without making them, --name sets the server name, and naming clients (tg-mcp-install opencode cursor) limits it to those. Existing config is merged rather than replaced, a .bak is kept, and a config file it cannot parse is skipped with a warning rather than overwritten.

Client	How it is registered
Claude Code	claude mcp add
Codex	codex mcp add
opencode	~/.config/opencode/opencode.json
Claude Desktop	claude_desktop_config.json
Cursor	~/.cursor/mcp.json
Windsurf	~/.codeium/windsurf/mcp_config.json

The rest of this section is the same thing by hand. Under every format it is one command and three arguments:

command	uvx
args	--from, git+https://github.com/Abdk4Moura/tg-mcp, tg-mcp

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.

opencode

opencode does not use mcpServers. Its key is mcp, the command is a single array rather than a command plus args, and each server declares its type. Add to ~/.config/opencode/opencode.json (or opencode.json / .opencode/opencode.json in a project, for that project only):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "telegram": {
      "type": "local",
      "command": ["uvx", "--from", "git+https://github.com/Abdk4Moura/tg-mcp", "tg-mcp"],
      "enabled": true
    }
  }
}

Environment variables go in an environment object, not env. opencode mcp list shows the server and whether it connected.

opencode reads opencode.json and opencode.jsonc and merges them, so if your config is a commented .jsonc you can drop the block above into a plain opencode.json beside it and leave the commented file alone. That is what tg-mcp-install does.

opencode mcp add telegram also works, but it prompts for the command interactively, so it is not scriptable for a local server the way claude mcp add is. The --url flag on that command is for remote servers only.

Codex

codex mcp add telegram -- uvx --from git+https://github.com/Abdk4Moura/tg-mcp tg-mcp

Codex stores this in ~/.codex/config.toml. codex mcp list shows it.

Anything else

Give the client the same command and args from the table at the top of this section, in whatever shape its own MCP documentation specifies.

If uvx is not on PATH

Some clients launch with a minimal environment and will not find uvx. Use its absolute path 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, listed separately under Settings → Devices and revocable on its own.

Copying session.session between machines also works, but both then share one session identity: revoking it logs out both, and a login from a very different IP can trip Telegram'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