Telegram MCP — AIエージェント向けローカル読み取り専用アクセス

ローカルMCPサーバーは、Codex、Claude、その他のMCPクライアントに3つのツールを提供します:

サーバーは読み取り専用でのみ動作します。コードにはメッセージの送信、編集、削除ツールはありません。サーバーはSTDIO経由でローカルに起動し、意図的にネットワークHTTP/SSEアクセスを提供しません。

対応クライアント

• ChatGPT/Codex Desktop;

• Codex CLI および IDE extension;

• Claude Code;

• Claude Desktop;

• STDIOをサポートする任意のローカルMCPクライアント。

ローカルサーバーは chatgpt.com、claude.ai、携帯電話、その他のコンピューターでは直接動作しません。これらの環境では、お使いのマシン上でプロセスを起動できないためです。

Related MCP server: tdl-mcp

必要なもの

• Windows 10/11、macOS、または Linux;

• Git;

• Python 3.10+;

• サポートされているMCPクライアントが少なくとも1つ。

初心者向けインストール

1. ターミナルを開く

• macOS: Command + Space → Terminal と入力 → Enter。

• Windows: スタートメニュー → PowerShell と入力 → PowerShell を開きます。

• Linux: Ctrl + Alt + T を押すか、ターミナルアプリを開きます。

2. プロジェクトをダウンロード

macOS/Linux:

git clone https://github.com/iamalexzatcepin/telegram-mcp-template.git ~/telegram-mcp
cd ~/telegram-mcp

Windows PowerShell:

git clone https://github.com/iamalexzatcepin/telegram-mcp-template.git "$env:USERPROFILE\telegram-mcp"
cd "$env:USERPROFILE\telegram-mcp"

GitHub がリポジトリが見つからないと報告する場合、お使いのアカウントにプライベートリポジトリへのアクセス権がまだありません。

3. Telegram API ID と API Hash を取得

1. my.telegram.org を開きます。

2. 電話番号でログインします。

3. API development tools を開きます。

4. アプリケーションを作成します（例: Local Telegram MCP）。

5. api_id と api_hash を保存します。

api_hash、ログインコード、クラウドパスワードをAIチャットに送信しないでください。

ローカルの .env を作成します。

macOS/Linux:

cp .env.example .env
nano .env

Nano での保存: Ctrl + O → Enter → Ctrl + X。

Windows PowerShell:

Copy-Item .env.example .env
notepad .env

ファイルをローカルで記入します:

TELEGRAM_API_ID=ваш_api_id
TELEGRAM_API_HASH=ваш_api_hash

4. 依存関係をインストールして Telegram にログイン

macOS/Linux:

bash setup.sh

Windows PowerShell:

powershell -ExecutionPolicy Bypass -File setup.ps1

スクリプトが Python 3.10+ を自動的に見つけ、.venv を作成し、依存関係をインストールして、電話番号、Telegram のコード、有効になっている場合はクラウドパスワードを要求します。これらは自分のターミナルにのみ入力してください。

エージェントへの接続

すべての例で、セットアップスクリプトが出力する絶対パスを使用してください。コマンドは .venv 内の Python で、引数は telegram_mcp_server.py です。

Codex CLI と ChatGPT/Codex Desktop

macOS/Linux:

codex mcp add telegram -- "$HOME/telegram-mcp/.venv/bin/python" "$HOME/telegram-mcp/telegram_mcp_server.py"
codex mcp get telegram

Windows PowerShell:

codex mcp add telegram -- "$env:USERPROFILE\telegram-mcp\.venv\Scripts\python.exe" "$env:USERPROFILE\telegram-mcp\telegram_mcp_server.py"
codex mcp get telegram

ChatGPT/Codex Desktop では、Settings → MCP servers → Add server を開き、STDIO を選択して、同じ Command と Arguments を指定することもできます。保存後、Restart をクリックします。同じ Codex ホストのローカルクライアントは、~/.codex/config.toml 設定を共有します。

Claude Code

macOS/Linux:

claude mcp add --transport stdio --scope user telegram -- "$HOME/telegram-mcp/.venv/bin/python" "$HOME/telegram-mcp/telegram_mcp_server.py"
claude mcp get telegram

Windows PowerShell:

claude mcp add --transport stdio --scope user telegram -- "$env:USERPROFILE\telegram-mcp\.venv\Scripts\python.exe" "$env:USERPROFILE\telegram-mcp\telegram_mcp_server.py"
claude mcp get telegram

新しい Claude Code セッションを開始し、/mcp と入力します。user スコープにより、そのユーザーのさまざまなローカルプロジェクトでサーバーを利用できるようになります。

Claude Desktop

Developer/MCP 設定を開き、ローカル STDIO サーバーを追加します。お使いの Claude Desktop のバージョンが JSON 設定を使用している場合は、他のサーバーを保持したままオブジェクトを追加します:

{
  "mcpServers": {
    "telegram": {
      "command": "/absolute/path/to/telegram-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/telegram-mcp/telegram_mcp_server.py"]
    }
  }
}

ファイルの一般的な場所:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json;

• Windows: %APPDATA%\Claude\claude_desktop_config.json。

Claude Desktop を完全に再起動し、新しいチャットを開きます。

その他の STDIO MCP クライアント

同等の設定を使用します:

{
  "mcpServers": {
    "telegram": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["/absolute/path/to/telegram_mcp_server.py"]
    }
  }
}

最終確認

エージェントに依頼します:

telegram の list_chats を limit=10 で使用し、名前、タイプ、未読メッセージの数を表示してください。

エージェントが実際にチャットのリストを返すまで、インストールは完了と見なさないでください。

複数アカウント

サーバーは default、work、personal などの個別のローカルセッションをサポートしています。手順は docs/MULTI_ACCOUNT.md にあります。

AIエージェント向け手順

Codex、Claude、または別のエージェントがインストールを実行する場合は、docs/AGENT_SETUP.md を完全に読み、それに従うように依頼してください。このファイルには、セキュリティルールとさまざまな OS 向けの分岐が記載されています。

セキュリティと制限

• .env と sessions/ は Git から除外されています。

• .session ファイルはアカウントへのアクセスを許可します。コピーしたり公開したりしないでください。

• メディアファイルはダウンロードされず、has_media フラグのみが返されます。

• Telegram へのリクエストはお使いのアカウントの代わりに実行され、Telegram の制限に従います。

• 同じ .session で 2 つの操作を同時に実行しないでください。

• このサーバーをインターネットに公開しないでください。

詳細: SECURITY.md。

うまくいかない場合

docs/TROUBLESHOOTING.md を参照してください。

開発

.venv/bin/python -m unittest discover -s tests -v

プロジェクト構成:

ライセンス

MIT — 著作権表示とライセンス文を保持する限り、プロジェクトの使用、変更、再配布が可能です。