Telegram Hosted MCP

克劳德电报MCP服务器

一个托管的多租户Telegram MCP（模型上下文协议）服务器，使Claude能够代表用户与Telegram进行交互。使用FastAPI、Telethon和OAuth 2.0身份验证构建。

特性

• 73电报工具 -完整的Telegram自动化，包括聊天、消息、联系人、群组、频道等
• 多租户架构 -单一部署通过隔离的Telegram会话为多个用户提供服务
• OAuth 2.0+PKCE -与Claude Teams兼容的安全身份验证流程
• 基于Web的Telegram认证 -用户通过电话/短信验证连接他们的Telegram帐户（不需要CLI）
• 加密会话存储 -使用AES-256加密存储的电报会话
• 铁路准备就绪 -使用PostgreSQL一键部署到Railway

______________________________________________________________________

可用工具（共73个）

Chat & Group Management (21 tools)

Messaging (24 tools)

Contact Management (12 tools)

User & Profile (5 tools)

Search & Discovery (4 tools)

Privacy & Settings (6 tools)

Drafts (3 tools)

______________________________________________________________________

部署

先决条件

1. 电报API证书 -从 my.telegram.org:

- 转到“API开发工具” - 创建新应用程序 - 注意 api_id 和 api_hash

1. 铁路账户 -注册地址： railway应用程序

部署到铁路

# Clone the repository
git clone https://github.com/your-org/telegram-hosted-mcp.git
cd telegram-hosted-mcp

# Install Railway CLI
npm install -g @railway/cli

# Login to Railway
railway login

# Create a new project
railway init

# Add PostgreSQL
railway add --plugin postgresql

# Set environment variables
railway variables set TELEGRAM_API_ID=your_api_id
railway variables set TELEGRAM_API_HASH=your_api_hash
railway variables set JWT_SECRET=$(openssl rand -hex 32)
railway variables set ENCRYPTION_KEY=$(python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())")
railway variables set BASE_URL=https://your-app.up.railway.app
railway variables set ALLOWED_REDIRECT_URIS=https://claude.ai/oauth/callback

# Deploy
railway up

环境变量

生成加密密钥：

python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

重要提示： 如果铁路设置 DATABASE_URL 作为 postgresql://...，将其更新为 postgresql+asyncpg://...

______________________________________________________________________

Claude团队设置

步骤1：注册OAuth客户端

部署后，为Claude Teams注册OAuth客户端：

curl -X POST https://your-app.up.railway.app/oauth/register \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "Claude Teams",
    "redirect_uris": ["https://claude.ai/oauth/callback"]
  }'

答复：

{
  "client_id": "abc123...",
  "client_secret": "secret456...",
  "client_name": "Claude Teams",
  "redirect_uris": ["https://claude.ai/oauth/callback"]
}

保存 client_id 和 client_secret.

步骤2：在Claude Teams管理中添加MCP服务器

1. 去你的 Claude Teams管理仪表板
2. 引导到 集成 → MCP服务器
3. 点击 添加MCP服务器
4. 填写配置：

1. 点击 保存

步骤3：用户连接Telegram

当团队成员首次使用Telegram工具时：

1. 克劳德提示他们授权Telegram连接
2. 他们点击“连接”并被重定向到您的OAuth服务器
3. 在OAuth之后，他们会看到一个web表单来输入他们的 电报电话号码 （国际格式，例如+1234567890）
4. Telegram发送 短信验证码 到他们的手机
5. 他们在网络表单上输入代码
6. 如果他们启用了2FA，则输入2FA密码
7. 成功！他们被重定向回克劳德，并连接了Telegram

用户只需要做一次。 他们的会话在对话中持续进行。

______________________________________________________________________

Claude桌面/个人设置

对于个人Claude用户（不在团队中），请使用支持MCP的Claude Desktop。

步骤1：注册OAuth客户端

curl -X POST https://your-app.up.railway.app/oauth/register \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "Claude Desktop",
    "redirect_uris": ["http://localhost:3000/callback"]
  }'

步骤2：配置Claude桌面

添加到您的Claude Desktop配置文件中：

macOS： ~/.config/claude/claude_desktop_config.json 窗户： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "telegram": {
      "url": "https://your-app.up.railway.app/mcp",
      "transport": "http",
      "auth": {
        "type": "oauth2",
        "authorizationUrl": "https://your-app.up.railway.app/oauth/authorize",
        "tokenUrl": "https://your-app.up.railway.app/oauth/token",
        "clientId": "YOUR_CLIENT_ID",
        "clientSecret": "YOUR_CLIENT_SECRET",
        "scopes": ["telegram:read", "telegram:write"]
      }
    }
  }
}

第三步：连接你的电报

1. 重新启动克劳德桌面
2. 开始新的对话
3. 问克劳德： *“列出我的Telegram聊天记录”*
4. Claude将提示您授权-单击链接
5. 在浏览器中完成Telegram电话验证
6. 回到克劳德身边——你联系上了！

______________________________________________________________________

用法示例

一旦连接，问克劳德这样的问题：

读取消息

"Show me my recent Telegram chats"
"Get the last 20 messages from the 'Family' group"
"Search my Telegram for messages about 'meeting notes'"
"What did John send me yesterday?"

发送消息

"Send a message to @username saying 'Hello, how are you?'"
"Reply to the last message in 'Work Team' with 'Sounds good!'"
"Forward that message to the 'Archive' chat"

组管理

"Create a new group called 'Project Alpha' and add @user1 and @user2"
"Show me the admins in the 'Company' channel"
"Promote @newadmin to admin in 'My Group'"
"Remove the person who keeps spamming from the group"

交互式功能

"Create a poll in the family chat: 'What should we have for dinner?' with options Pizza, Sushi, Tacos"
"React with 👍 to John's last message"
"Press the 'Confirm' button on that bot message"

组织

"Archive all chats I haven't messaged in over a month"
"Mute the 'Announcements' channel"
"Show me my blocked users"

______________________________________________________________________

API 参考

OAuth端点

电报身份验证端点

MCP端点

健康检查

______________________________________________________________________

故障排除

“连接到MCP服务器时出错”

1. 检查服务器运行状况：

   curl https://your-app.up.railway.app/health

1. 验证OAuth元数据：

   curl https://your-app.up.railway.app/.well-known/oauth-authorization-server

1. 检查环境变量：

- BASE_URL 必须与实际部署的URL完全匹配 - ALLOWED_REDIRECT_URIS 必须包含Claude回调URL

“找不到电报会话”

用户需要完成Telegram身份验证：

1. 通过要求Claude使用Telegram工具再次触发OAuth流
2. 完成电话/短信验证

“Fernet密钥无效”

加密密钥必须是有效的Fernet密钥。生成一个：

python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

“数据库连接失败”

确保 DATABASE_URL 包含异步驱动程序：

postgresql+asyncpg://user:pass@host:port/db

如果铁路将其设置为 postgresql://...，更新变量。

“电话号码无效”

电话号码必须采用国际格式，并带有国家代码：

• 对的： +14155551234
• 错误： 415-555-1234

铁路部署失败

检查日志：

railway logs --build   # Build logs
railway logs           # Runtime logs

______________________________________________________________________

安全

______________________________________________________________________

本地开发

设置

# Clone repository
git clone https://github.com/your-org/telegram-hosted-mcp.git
cd telegram-hosted-mcp

# Install uv (if not installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies
uv sync

# Create .env file
cat > .env << EOF
DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/telegram_mcp
TELEGRAM_API_ID=your_api_id
TELEGRAM_API_HASH=your_api_hash
JWT_SECRET=$(openssl rand -hex 32)
ENCRYPTION_KEY=$(python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())")
BASE_URL=http://localhost:8000
ALLOWED_REDIRECT_URIS=http://localhost:3000/callback
EOF

# Start PostgreSQL (using Docker)
docker run -d --name postgres -e POSTGRES_PASSWORD=postgres -p 5432:5432 postgres:15

# Run migrations
alembic upgrade head

# Start server
uvicorn app.main:app --reload

测试

# Test OAuth metadata
curl http://localhost:8000/.well-known/oauth-authorization-server

# Register a test client
curl -X POST http://localhost:8000/oauth/register \
  -H "Content-Type: application/json" \
  -d '{"client_name": "Test", "redirect_uris": ["http://localhost:3000/callback"]}'

______________________________________________________________________

项目结构

telegram-hosted-mcp/
├── app/
│   ├── main.py              # FastAPI application entry point
│   ├── config.py            # Environment configuration (pydantic-settings)
│   ├── database.py          # SQLAlchemy async engine setup
│   ├── models.py            # Database models (users, clients, sessions)
│   ├── auth/
│   │   ├── oauth.py         # OAuth 2.0 endpoints (authorize, token, register)
│   │   ├── tokens.py        # JWT token creation and verification
│   │   └── telegram.py      # Telegram phone/SMS/2FA auth flow
│   ├── mcp/
│   │   ├── server.py        # MCP server (73 tool definitions + routing)
│   │   ├── middleware.py    # Bearer token validation, audit logging
│   │   └── tools/
│   │       ├── __init__.py
│   │       ├── chats.py     # 21 chat/group management tools
│   │       ├── messages.py  # 24 messaging tools
│   │       ├── contacts.py  # 12 contact management tools
│   │       ├── users.py     # 9 user/profile/discovery tools
│   │       ├── privacy.py   # 6 privacy/settings tools
│   │       └── drafts.py    # 3 draft tools
│   ├── telegram/
│   │   ├── client_pool.py   # Multi-tenant Telethon client pool with LRU
│   │   └── session_store.py # Fernet-encrypted session storage
│   └── templates/           # HTML templates for auth flow
│       ├── phone.html       # Phone number entry
│       ├── code.html        # SMS code entry
│       ├── 2fa.html         # 2FA password entry
│       └── success.html     # Success page
├── alembic/                  # Database migrations
├── Dockerfile               # Container configuration
├── pyproject.toml           # Python dependencies
├── railway.toml             # Railway deployment config
└── README.md

______________________________________________________________________

学分

• 灵感源自 奇威尔/电报mcp
• 建于 电视募捐
• MCP协议 Anthropic

许可证

MIT许可证