MCP Personal Assistant Agent
A versatile personal assistant AI agent built with the Model Context Protocol (MCP) that helps with calendar, tasks, emails, and more.
Overview
This project is a Model Context Protocol (MCP) server that provides a set of tools for a personal assistant agent. It can be integrated with MCP clients like Claude for Desktop to give AI assistants the ability to:
- Manage calendar events
- Track tasks and to-dos
- Read and send emails
- Search the web and retrieve information
- Control smart home devices
Requirements
**IMPORTANT:** Python 3.10 or higher is required for the MCP SDK. The server will not work with earlier Python versions.
- Python 3.10+
- MCP SDK 1.2.0+
- Required Python packages (see requirements.txt)
Installation
- Clone the repository:
- Ensure you have Python 3.10+:
- If your system Python is older than 3.10, set up a compatible environment:
- Install dependencies:
- Configure environment variables by copying the example file:
- Edit the `.env` file with your API credentials and settings.
Running the Server
Start the MCP server with:
The server will start and listen for MCP client connections.
Connecting to Claude for Desktop
- Install [Claude for Desktop](https://claude.ai/desktop)
- Configure Claude for Desktop to use this MCP server by editing the configuration file at: - MacOS/Linux: `~/Library/Application Support/Claude/claude_desktop_config.json` - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Add the following configuration:
If you're using a virtual environment, make sure to point to the Python executable in that environment.
- Restart Claude for Desktop
Available Tools
Calendar
- `get_events`: Retrieve upcoming calendar events
- `create_event`: Schedule a new calendar event
Tasks
- `list_tasks`: View all tasks or filter by status
- `add_task`: Create a new task
- `update_task_status`: Mark tasks as pending, in-progress, or completed
- `get_emails`: List recent emails from your inbox
- `read_email`: View the full content of a specific email
- `send_email`: Compose and send a new email
Knowledge
- `web_search`: Search the web for information
- `get_weather`: Get current weather information
- `get_news`: Retrieve latest news articles
Smart Home
- `list_devices`: View all smart home devices
- `control_device`: Control smart home devices (lights, thermostats, etc.)
- `get_device_state`: Get detailed information about a device's current state
Configuration
The server requires various API keys and credentials to access different services:
- **Google API**: For calendar and email functionality (OAuth2 credentials)
- **Weather API**: For weather information
- **News API**: For news retrieval
- **Home Assistant**: For smart home control
Refer to the `.env.example` file for all configurable options.
Troubleshooting
Python Version Issues
If you see an error like:
You need to upgrade your Python version or use a virtual environment with Python 3.10+.
MCP SDK Installation Issues
If you encounter problems installing the MCP SDK:
Make sure you're using Python 3.10+ and pip is updated:
Development
To add new functionality to the server, you can:
- Create a new module in the `modules/` directory
- Implement functions with the `@mcp.tool()` decorator
- Import your module in `mcp_server.py`
License
MIT
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.