MCP Telegram

这是一个使用 TypeScript 实现的 MCP (模型上下文协议) 服务器，用于通过 MTProto 与 Telegram 交互，构建于 FastMCP 之上。

概述

本项目提供了一系列工具，用于通过 MTProto 协议与 Telegram 进行交互，并通过 MCP 服务器提供给像 Claude 这样的人工智能模型使用。

安装

# 安装依赖
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 [options]

# 从 Telegram 登出
npm run logout
# 或者
npx mcp-telegram logout

mcp 命令的 CLI 选项：

• -t, --transport <type>: 传输类型 (stdio, sse)，默认为 'stdio'
• -p, --port <number>: HTTP/SSE 传输的端口，默认为 3000
• -e, --endpoint <path>: SSE 传输的端点，默认为 '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 传输的端口，默认为 3000
• ENDPOINT: SSE 传输的端点，默认为 'mcp'
• LOG_LEVEL: 日志级别，默认为 'info'

这些可以在项目根目录下的 .env 文件中设置。

开发

开发需要 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: Boolean，仅显示未读对话（默认：false）
• archived: Boolean，包括已存档的对话（默认：false）
• ignorePinned: Boolean，忽略置顶对话（默认：false）

listMessages

列出给定对话、聊天或频道中的消息。

参数：

• dialogId: String，要列出消息的对话 ID
• unread: Boolean，仅显示未读消息（默认：false）
• limit: Number，要检索的最大消息数（默认：100）

项目结构

src/
├── config.ts               # 应用程序配置
├── index.ts                # 主要服务器实现
├── mcp.ts                  # CLI 入口点
├── tools/                  # 工具实现
│   ├── index.ts            # 工具导出
│   └── telegramTools.ts    # Telegram 工具
├── lib/           # 核心 Telegram 功能
│   ├── index.ts            # 模块导出
│   ├── telegram.ts         # Telegram 客户端功能
└── utils/                  # 实用程序
    ├── errorHandler.ts     # 错误处理实用程序
    └── logger.ts           # 日志记录实用程序

许可证

本项目采用 MIT 许可证 - 有关详细信息，请参阅 LICENSE 文件。