MCP Telegram

🚀 MCP 電報協議

這是一個基於 TypeScript 實現的 MCP（模型上下文協議）服務器，藉助 MTProto 協議與 Telegram 進行交互，採用 FastMCP 構建。它為 AI 模型（如 Claude）提供了與 Telegram 交互的能力。

🚀 快速開始

此項目提供了一系列工具，可通過 MTProto 協議與 Telegram 進行交互，並藉助 MCP 服務器將這些功能提供給像 Claude 這樣的 AI 模型使用。

📦 安裝指南

# 安裝依賴項
npm install

# 構建項目
npm run build

💻 使用示例

基礎用法

CLI 命令

應用程序提供了以下 CLI 命令：

# 登錄到 Telegram
npm run sign-in
# 或者
npx mcp-telegram sign-in

# 啟動 MCP 服務器
npm run mcp
# 或 
npx mcp-telegram mcp [選項]

# 註銷 Telegram 賬戶
npm run logout
# 或
npx mcp-telegram logout

mcp 命令的 CLI 選項：

• -t, --transport <類型>：傳輸類型（stdio、sse），默認為 'stdio'
• -p, --port <數字>：HTTP/SSE 傳輸端口， defaults to 3000
• -e, --endpoint <路徑>：SSE 傳輸的端點， defaults to 'mcp'

啟動 MCP 服務器

使用 stdio 傳輸啟動 MCP 服務器（默認，用於 Cursor AI 等工具）：

npm run start
# 或者
npm run mcp

你也可以通過程序啟動服務器：

import server, { startServer } from 'mcp-telegram';

// 使用配置啟動服務器
startServer(server);

環境變量

應用程序使用以下環境變量：

• TELEGRAM_API_ID：你的 Telegram API ID
• TELEGRAM_API_HASH：你的 Telegram API Hash
• TRANSPORT_TYPE：傳輸類型（'stdio'、'http' 或 'sse'），默認為 'stdio'
• PORT：HTTP 或 SSE 傳輸的端口， defaults to 3000
• ENDPOINT：SSE 傳輸的端點， defaults to 'mcp'
• LOG_LEVEL：日誌級別， defaults to 'info'

這些變量可以在項目根目錄的 .env 文件中設置。

高級用法

import { createServer } from 'mcp-telegram';

const server = createServer({
  port: 3000,
  endpoint: 'mcp',
  transportType: 'stdio'
});

server.start();

🔧 技術細節

開發

開發需要 Node.js 版本 18 或更高。

# 在開發模式下運行
npm run dev

# 格式化代碼
npm run lint

# 運行測試
npm run test

FastMCP 集成

服務器使用 FastMCP 實現，它提供了現代的 TypeScript 版本的模型上下文協議。它支持 stdio 和 SSE 傳輸，使其與不同的客戶端集成方法兼容。

服務器傳輸

• stdio：默認傳輸，適用於直接與 Cursor AI 等工具集成
• sse：Server-Sent Events 傳輸，用於即時通信

可用工具

listDialogs

列出可用的對話、聊天和頻道。 參數：

• unread：布爾值，顯示僅未讀對話（默認：false）
• archived：布爾值，包含已存檔的對話（默認：false）
• ignorePinned：布爾值，忽略固定對話（默認：false）

listMessages

在指定的對話、聊天或頻道中列出消息。 參數：

• dialogId：字符串，要列出消息的對話 ID
• unread：布爾值，顯示僅未讀消息（默認：false）
• limit：數字，要獲取的最大消息數（默認：100）

項目結構

src/
├── config.ts               # 應用配置
├── index.ts                # 主文件
├── server.ts               # 服務器實現
└── utils/                 # 工具函數
    └── logger.ts          # 日誌工具

📚 詳細文檔

此文檔介紹瞭如何使用 MCP 協議與 Telegram 交互，並提供了完整的代碼示例和配置選項。