MCP Server Setup Instructions

MCP 服务设置说明

此 MCP 服务提供了一个 Telegram AI Agent，可使用 Ionos AI 模型与 Gmail、Google Calendar 和 Google Tasks 交互。

前提条件

1. Python 3.8 或更高版本
2. 已启用 API 的 Google Cloud 项目
3. Telegram 机器人令牌
4. Ionos AI API 密钥

步骤 1：安装依赖项

pip install -r requirements.txt

步骤 2：设置 Google Cloud

1. 前往 Google Cloud 控制台
2. 创建新项目或选择现有项目
3. 启用以下 API：
   • Gmail API
   • Google Calendar API
   • Google Tasks API
4. 创建 OAuth2 凭据：
   • 前往“凭据” → “创建凭据” → “OAuth 客户端 ID”
   • 选择“桌面应用”
   • 下载 JSON 文件并将其重命名为 credentials.json
   • 将其放在与脚本相同的目录中

步骤 3：设置 Telegram 机器人

1. 在 Telegram 上向 @BotFather 发送消息
2. 使用 /newbot 命令创建新机器人
3. 按照说明获取机器人令牌
4. 将令牌复制到 .env 文件中

步骤 4：设置 Ionos AI

1. 从 Ionos AI 服务获取 API 密钥
2. 将其添加到 .env 文件中

步骤 5：配置环境

1. 将 .env.example 复制为 .env
2. 填写所有必需的值：

cp .env.example .env
# Edit .env with your actual values

步骤 6：首次运行和身份验证

1. 首次运行服务：

python mcp_server.py

2. 脚本会提示你通过 Google 进行身份验证：

   • 屏幕上会显示一个 URL
   • 在浏览器中打开该 URL
   • 授予权限
   • 将授权码复制回终端

3. 凭据将保存到 token.pickle，供以后使用

用法

可用工具

1. send_telegram_message：通过 Telegram 发送消息
2. search_gmail：搜索 Gmail 邮件
3. create_calendar_event：创建 Google Calendar 活动
4. create_task：创建 Google Tasks 任务
5. ai_chat：与 Ionos AI 模型聊天

Telegram 命令

• /start - 初始化机器人
• 发送任意消息即可与 AI 聊天

交互示例

搜索 Gmail：

"Search for emails from [email protected]"

创建日历活动：

"Create a meeting for tomorrow at 2 PM for 1 hour about project review"

创建任务：

"Add a task to review the quarterly report by Friday"

文件结构

├── mcp_server.py          # Main MCP server
├── requirements.txt       # Python dependencies
├── .env                  # Environment variables
├── credentials.json      # Google OAuth2 credentials
├── token.pickle         # Saved Google authentication token
└── README.md            # This file

安全说明

1. 妥善保管 .env 文件，切勿将其提交到版本控制系统
2. token.pickle 文件包含敏感的身份验证数据
3. 在生产环境中使用 HTTPS
4. 定期轮换 API 密钥

故障排除

常见问题

1. “ModuleNotFoundError”：确保已安装所有依赖项
2. “Authentication failed”：检查 Google 凭据并重新运行身份验证
3. “Telegram bot not responding”：验证机器人令牌和网络连接
4. “Ionos AI errors”：检查 API 密钥和速率限制

日志

服务会记录重要事件。检查控制台输出中的错误消息和调试信息。

开发

扩展功能：

1. 在 setup_handlers() 方法中添加新工具
2. 为每个工具实现相应的方法
3. 根据需要更新资源列表
4. 部署前进行全面测试

生产环境部署

用于生产环境时：

1. 使用 systemd 或 supervisord 等进程管理器
2. 设置适当的日志记录
3. 配置防火墙规则
4. 使用特定于环境的配置
5. 设置监控和告警

API 速率限制

请留意 API 速率限制：

• Gmail API：每天 10 亿个配额单位
• Calendar API：每天 100 万次请求
• Tasks API：每天 50,000 次请求
• Ionos AI：请查看你的套餐限额

支持

遇到问题或有疑问时：

1. 检查日志中的错误消息
2. 确认所有凭据均正确
3. 分别测试各个组件
4. 查看 API 状态页面，确认服务是否中断