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

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.

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

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.

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

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