baazilakhlaque/vin-agent

VIN: Virtual Itinerary Navigator

A production-ready Model Context Protocol (MCP) server that transforms natural language into actionable calendar events, email notifications, and restaurant recommendations through seamless Google API integrations.

🎯 Problem Statement

Managing complex itineraries and event coordination is time-consuming and error-prone:

• Manual Calendar Management: Creating events, checking conflicts, and coordinating schedules across multiple participants
• Fragmented Communication: Sending separate emails for event details, venue suggestions, and booking confirmations
• Venue Discovery: Finding and evaluating nearby restaurants or venues for meetings and events
• Context Switching: Jumping between calendar apps, email clients, and restaurant search platforms

🚀 Solution

VIN (Virtual Itinerary Navigator) solves these challenges by providing a unified, AI-powered interface that:

• Automates Event Scheduling: Converts natural language requests into structured calendar events with conflict detection
• Streamlines Communication: Generates and sends formal email notifications to all participants
• Enhances Venue Discovery: Finds nearby restaurants with detailed information and booking capabilities
• Integrates Seamlessly: Works with Claude and other LLMs through the Model Context Protocol

✨ Features

📅 Smart Calendar Integration

• Natural language event creation with automatic time parsing
• Real-time conflict detection and resolution
• Attendee management with automatic email notifications
• Timezone-aware scheduling with flexible duration options

📧 Automated Email System

• Formal email generation for event notifications
• CC/BCC functionality for comprehensive communication
• Draft creation and direct sending capabilities

��️ Intelligent Venue Discovery

• Location-based restaurant search with customizable radius
• Detailed venue information (ratings, hours, contact details)
• Price level and cuisine type filtering
• Integration with Google Places API for real-time data

👥 Contact Management

• Built-in contact directory with email lookup
• Seamless integration with email and calendar tools
• JSON-based contact storage for easy management

🤖 LLM Integration

• Full MCP (Model Context Protocol) compliance
• Works with Claude, GPT-4, and other MCP-compatible LLMs
• Natural language processing for complex requests
• Context-aware responses with structured data

🛠️ Technology Stack

• Backend: Python 3.8+
• MCP Framework: FastMCP 2.0
• Google APIs: Gmail, Calendar, Places
• Authentication: OAuth 2.0 with automatic token refresh
• Data Storage: JSON-based contact management
• Environment: Virtual environment with dependency management
• Package Manager: uv (recommended) or pip

📋 Prerequisites

• Python 3.8 or higher
• Google Cloud Platform account
• Google APIs enabled (Gmail, Calendar, Places)
• OAuth 2.0 credentials configured
• uv (recommended for faster dependency management)

Quick Start

1. Clone the Repository

git clone https://github.com/yourusername/vin-agent.git
cd vin-agent

2. Set Up Virtual Environment with uv (Recommended)

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create virtual environment and install dependencies
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -r requirements.txt

3. Alternative: Set Up with pip

python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -r requirements.txt

4. Configure Google APIs

1. Create a Google Cloud Project
2. Enable Gmail API, Calendar API, and Places API
3. Create OAuth 2.0 credentials
4. Download credentials.json and save it in .config/vin-agent/

5. Set Up Environment Variables

cp .env.example .env
# Edit .env with your configuration

6. Authenticate with Google

# With uv
uv run oauth_setup.py

# Or with python
python oauth_setup.py

7. Start the MCP Server

# With uv (recommended)
uv run mcp-server.py

# Or with python
python mcp-server.py

🤖 Claude Desktop Integration

As an example, to use VIN with Claude Desktop, add the following configuration to your Claude Desktop settings:

{
  "mcpServers": {
    "vin": {
      "command": "/Users/baazilakhlaque/.local/bin/uv", # replace with global path to your uv installation
      "args": [
        "--directory",
        "/Users/baazilakhlaque/Desktop/vin", # replace with global path to repo
        "run",
        "mcp-server.py"
      ]
    }
  }
}

Note: Update the paths to match your actual installation directory and username.

⚙️ Configuration

Environment Variables

# Your Gmail address (used as sender)
USER_EMAIL=your.email@gmail.com

# Google Maps API Key (for venue search)
GOOGLE_MAPS_API_KEY=your_google_maps_api_key_here

# Default timezone for events
DEFAULT_TIMEZONE=America/New_York

# Default city for venue searches
CITY_DEFAULT=New York, NY

Contact Management

Create contacts.json file to manage your contact directory in the following format:

{
    "John Doe": "john.doe@company.com",
    "Jane Smith": "jane.smith@company.com"
}

📖 Usage Examples

Calendar Event Creation

"Schedule a team meeting tomorrow at 3pm for 1 hour with John and Jane"

Email Notifications

"Send an email to John and Jane about the project update"

Restaurant Discovery

"Suggest restaurants in downtown Dallas, Texas."

�� Security & Privacy

• OAuth 2.0 Authentication: Secure authentication
• Token Management: Automatic refresh token handling

📄 License

This project is licensed under the MIT License - see the file for details.

Acknowledgments

• FastMCP for the MCP framework
• Google APIs for Gmail, Calendar, and Places integration
• Anthropic for Claude and MCP protocol
• uv for fast Python package management