MCP 个人助理代理

一个多功能的个人助理 AI 代理，基于模型上下文协议 (MCP) 构建，可帮助处理日历、任务、电子邮件等。

概述

本项目是一个模型上下文协议 (MCP) 服务器，为个人助理代理提供了一组工具。它可以与 MCP 客户端（如 Claude for Desktop）集成，使 AI 助手能够：

• 管理日历事件
• 跟踪任务和待办事项
• 阅读和发送电子邮件
• 搜索网络并检索信息
• 控制智能家居设备

要求

⚠️ 重要提示： MCP SDK 需要 Python 3.10 或更高版本。该服务器无法在早期版本的 Python 上运行。

• Python 3.10+
• MCP SDK 1.2.0+
• 必需的 Python 包（请参阅 requirements.txt）

安装

1. 克隆存储库：

git clone https://github.com/yourusername/mcp-pa-ai-agent.git
cd mcp-pa-ai-agent

2. 确保您已安装 Python 3.10+：

python --version

3. 如果您的系统 Python 版本低于 3.10，请设置一个兼容的环境：

# 使用 conda
conda create -n mcp-env python=3.10
conda activate mcp-env

# 或者使用 venv（如果 Python 3.10+ 安装在其他位置）
python3.10 -m venv venv
source venv/bin/activate  # 在 Windows 上：venv\Scripts\activate

4. 安装依赖项：

pip install -r requirements.txt

5. 通过复制示例文件来配置环境变量：

cp .env.example .env

6. 使用您的 API 凭据和设置编辑 .env 文件。

运行服务器

使用以下命令启动 MCP 服务器：

python mcp_server.py

服务器将启动并侦听 MCP 客户端连接。

连接到 Claude for Desktop

1. 安装 Claude for Desktop

2. 通过编辑以下位置的配置文件，将 Claude for Desktop 配置为使用此 MCP 服务器：

   • MacOS/Linux: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

3. 添加以下配置：

{
  "mcpServers": {
    "personal-assistant": {
      "command": "/path/to/python",
      "args": [
        "/absolute/path/to/mcp-pa-ai-agent/mcp_server.py"
      ]
    }
  }
}

如果您使用的是虚拟环境，请确保指向该环境中的 Python 可执行文件。

4. 重启 Claude for Desktop

可用工具

日历

• get_events: 检索即将到来的日历事件
• create_event: 安排新的日历事件

任务

• list_tasks: 查看所有任务或按状态筛选
• add_task: 创建新任务
• update_task_status: 将任务标记为待处理、进行中或已完成

电子邮件

• get_emails: 列出收件箱中的最近电子邮件
• read_email: 查看特定电子邮件的完整内容
• send_email: 撰写并发送新电子邮件

知识

• web_search: 在网络上搜索信息
• get_weather: 获取当前天气信息
• get_news: 检索最新的新闻文章

智能家居

• list_devices: 查看所有智能家居设备
• control_device: 控制智能家居设备（灯、恒温器等）
• get_device_state: 获取有关设备当前状态的详细信息

配置

服务器需要各种 API 密钥和凭据才能访问不同的服务：

• Google API: 用于日历和电子邮件功能（OAuth2 凭据）
• Weather API: 用于天气信息
• News API: 用于新闻检索
• Home Assistant: 用于智能家居控制

有关所有可配置选项，请参阅 .env.example 文件。

故障排除

Python 版本问题

如果您看到类似以下的错误：

Error: Python 3.10 or higher is required for the MCP server.

您需要升级您的 Python 版本或使用带有 Python 3.10+ 的虚拟环境。

MCP SDK 安装问题

如果您在安装 MCP SDK 时遇到问题：

ERROR: Could not find a version that satisfies the requirement mcp>=1.2.0

请确保您使用的是 Python 3.10+ 并且 pip 已更新：

pip install --upgrade pip

开发

要向服务器添加新功能，您可以：

1. 在 modules/ 目录中创建一个新模块
2. 使用 @mcp.tool() 装饰器实现函数
3. 在 mcp_server.py 中导入您的模块

许可证

MIT

贡献

欢迎贡献！请随时提交 Pull Request。