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.

Related MCP server: telegram-mcp

Setting it up for other agents

Every MCP client needs the same two things. Whatever the config format, this is all it is:

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.

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:

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 the mcpServers block above. Check that client's own MCP documentation, and give it the same command 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 absolute path as the command (which uvx to find it, commonly ~/.local/bin/uvx).

Tools

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

Local development

uv run --directory /path/to/tg-mcp tg-mcp