使用说明
电报机器人mcp
A. 模型上下文协议（MCP） 暴露的服务器 电报机器人API 作为工具——让克劳德和其他MCP客户端通过Telegram机器人发送消息、照片、民意调查等。
建于 FastMCP python无需外部身份验证代理——内置OIDC/JWT身份验证。
特性
- 工具:
get_me,list_chats,send_message,send_photo,send_document,send_location,send_poll,edit_message_text,delete_message,get_chat,get_chat_member_count - 三种身份验证模式：stdio（无身份验证）、静态承载令牌、完整的OIDC OAuth2代理（例如Authentik、Keycloak）
- 运输：stdio（克劳德桌面）+可流式HTTP（远程/K8s）
- 多拱形Docker镜像：linux/amd64+linux/arm64
快速开始
stdio（克劳德桌面/本地）
pip install .
export TELEGRAM_BOT_TOKEN=your_token_here
python -m telegram_bot_mcp
添加到克劳德桌面 claude_desktop_config.json:
{
"mcpServers": {
"telegram": {
"command": "python",
"args": ["-m", "telegram_bot_mcp"],
"env": {
"TELEGRAM_BOT_TOKEN": "your_token_here"
}
}
}
}
流式HTTP（远程）
export TELEGRAM_BOT_TOKEN=your_token_here
export AUTH_TOKEN=your_secret_bearer_token # optional: require auth
python -m telegram_bot_mcp --transport streamable-http --port 8000
从克劳德代码连接：
claude mcp add telegram --transport http https://your-host:8000/mcp \
--header "Authorization: Bearer your_secret_bearer_token"
OIDC OAuth2（生产）
完整的OAuth2流——服务器充当OIDC代理。用户通过您的身份提供者（Authentik、Keycloak、Auth0等）进行身份验证，并接收持续的会话 SESSION_LIFETIME_HOURS （默认：8小时）。
export TELEGRAM_BOT_TOKEN=your_token_here
export OIDC_DISCOVERY_URL=https://auth.example.com/application/o/my-app/.well-known/openid-configuration
export OIDC_CLIENT_ID=your_client_id
export OIDC_CLIENT_SECRET=your_client_secret
export BASE_URL=https://telegram-bot-mcp.example.com
python -m telegram_bot_mcp --transport streamable-http --port 8000
环境变量
| 变量 | 必填 | 描述 |
|---|---|---|
TELEGRAM_BOT_TOKEN |
是 | 来自的Bot令牌 @植物学家 |
OIDC_DISCOVERY_URL |
否* | OIDC发现URL--启用完整的OAuth2代理模式 |
OIDC_CLIENT_ID |
否* | OAuth2客户端ID |
OIDC_CLIENT_SECRET |
否* | OAuth2客户端机密 |
BASE_URL |
否* | 此服务器的公共基URL（OAuth2重定向所需） |
JWT_SIGNING_KEY |
否 | 用于签名会话JWTs的稳定密钥；如果未设置，则每次启动都是随机的 |
SESSION_LIFETIME_HOURS |
否 | 会话持续时间（小时）（默认值： 8) |
AUTH_TOKEN |
否 | 静态承载令牌（OIDC的更简单替代方案） |
KNOWN_CHATS |
否 | 预配置聊天： Name=chat_id,Name2=chat_id2 |
CHAT_STORE_PATH |
否 | 已发现聊天缓存的路径（默认值： ~/.local/share/fastmcp/chats.json) |
*必须将所有四个OIDC变量设置在一起才能启用OAuth2模式。
码头工人
docker run -p 8000:8000 \
-e TELEGRAM_BOT_TOKEN=your_token_here \
-v telegram-data:/data \
ghcr.io/your-org/telegram-bot-mcp:latest
命名卷(telegram-data:/data)在容器重新启动时持久化发现的聊天ID。
或者使用Docker Compose：
cp .env.example .env # fill in your token
docker compose up -d
许可证
麻省理工学院——见 许可证.
