MCP Telegram

🚀 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 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：布尔值，显示仅未读对话（默认：false）
• archived：布尔值，包含已存档的对话（默认：false）
• ignorePinned：布尔值，忽略固定对话（默认：false）

listMessages

在指定的对话、聊天或频道中列出消息。 参数：

• dialogId：字符串，要列出消息的对话 ID
• unread：布尔值，显示仅未读消息（默认：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 交互，并提供了完整的代码示例和配置选项。