🚀 MCP 电报协议
本项目是一个基于 TypeScript 实现的 MCP（模型上下文协议）服务器，借助 MTProto 协议实现与 Telegram 的交互，采用 FastMCP 构建。它提供了一系列工具，可让 AI 模型（如 Claude）通过 MCP 服务器与 Telegram 进行交互。
🚀 快速开始
本项目提供了一组工具，用于通过 MTProto 协议与 Telegram 交互，并将其提供给 AI 模型（如 Claude）使用。
📦 安装指南
# 安装依赖项
npm install
# 构建项目
npm run build
💻 使用示例
基础用法
应用程序提供了以下 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 传输端口，默认为 3000-e, --endpoint <路径>：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 IDTELEGRAM_API_HASH：你的 Telegram API HashTRANSPORT_TYPE：传输类型（'stdio'、'http' 或 'sse'），默认为 'stdio'PORT：HTTP 或 SSE 传输的端口，默认为 3000ENDPOINT：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：布尔值，显示仅未读对话（默认：false）archived：布尔值，包含已存档的对话（默认：false）ignorePinned：布尔值，忽略固定对话（默认：false）
listMessages
在指定的对话、聊天或频道中列出消息。 参数：
dialogId：字符串，要列出消息的对话 IDunread：布尔值，显示仅未读消息（默认：false）limit：数字，要获取的最大消息数（默认：100）
项目结构
src/
├── config.ts # 应用配置
├── index.ts # 主文件
├── server.ts # 服务器实现
└── utils/ # 工具函数
└── logger.ts # 日志工具
示例代码
import { createServer } from 'mcp-telegram';
const server = createServer({
port: 3000,
endpoint: 'mcp',
transportType: 'stdio'
});
server.start();
📚 详细文档
此文档介绍了如何使用 MCP 协议与 Telegram 交互，并提供了完整的代码示例和配置选项。