MailMind: MCP-Powered AI Gmail Assistant (CalHacks Fall 25)

MailMind connects GPT to Gmail via MCP. Our AI reasons through any email scenario, including meeting requests, follow-ups, and thank-yous, understanding context to craft and send the perfect message.

Comment

MailMind - AI-Powered Email Through Natural Conversation

Inspiration

We've all been there: switching between chat apps, email clients, and calendars just to send a simple follow-up or schedule a meeting. What if you could just tell an AI what you want to say, and it handles the rest?

During CalHacks 2025, we saw an opportunity to leverage the Model Context Protocol (MCP),a new standard for connecting LLMs to external tools, to bridge the gap between natural language and email. Our goal: make email as easy as having a conversation.

What It Does

MailMind is an AI email assistant that understands context and intent. You can:

  • Compose emails naturally: "Send a thank you email to the team for their hard work on the demo"
  • Build emails incrementally: Tell the AI the recipient first, then the subject, then the body - it remembers everything
  • Handle any scenario: Meeting requests, follow-ups, project updates, introductions - GPT-4 reasons through context to compose the perfect message
  • No app switching: Stay in one interface while the AI handles Gmail operations

Built on MCP architecture, MailMind connects GPT-4's reasoning capabilities directly to your Gmail account through a clean, conversational interface.

How We Built It

Architecture:

  • MCP Server (Python): Implements the Model Context Protocol to expose Gmail operations as callable tools
  • OAuth Flow: Secure Google authentication with proper token management
  • Flask Host (Python): Web server that bridges the UI with OpenAI's GPT-4 and our MCP server
  • LLM Integration: GPT-4o-mini with function calling to intelligently decide when to use tools
  • Conversation Memory: Session-based history tracking so the AI maintains context across messages

Tech Stack:

  • Python with uv package manager
  • Google Gmail API with OAuth 2.0
  • OpenAI GPT-4o-mini
  • Flask for backend
  • Vanilla JavaScript frontend
  • JSON-RPC 2.0 for MCP communication

Key Implementation:

  1. MCP server listens on stdin/stdout, exposing send_email as a structured tool
  2. Flask app spawns MCP server process, communicating via subprocess pipes
  3. User messages → GPT-4 with tool schemas → LLM decides to call send_email → MCP executes → Gmail API sends
  4. Conversation history stored in Flask sessions for multi-turn context

Challenges We Ran Into

1. MCP SDK Import Conflicts
We copied the MCP SDK into our repo for learning, but this created circular import issues. We initially tried to use the sophisticated LLMClient from the SDK, but kept hitting ModuleNotFoundError and path conflicts.

Solution: Pivoted to a simpler subprocess-based approach - spawning the MCP server as a child process and communicating via stdin/stdout JSON-RPC messages. Less elegant, but it works reliably.

2. Conversation Memory
Initially, the LLM would "forget" previous messages. A user could say "Send an email to John" then "The subject is Meeting Follow-up" then "Tell him thanks for yesterday" - but the LLM wouldn't remember John or the subject.

Solution: Implemented Flask session-based conversation storage. Each user gets a unique session ID, and we maintain their full conversation history, passing it to GPT-4 with each request. Now the AI truly remembers context.

3. OAuth Token Management
Google's OAuth flow generates credentials.json (app credentials) and token.json (user tokens with refresh tokens). We were unsure how to directly use this to grant gmail access to our MCP server

Solution: Created proper .gitignore rules, .env.example templates, and documented the OAuth flow. Implemented functionality for MCP server to take in credentials.json and abstract away individual email authentication to Google Cloud Console.

4. Tool Schema Conversion
MCP uses JSON Schema format for tool definitions, while OpenAI expects a slightly different format. Converting between the two required careful mapping.

Solution: Built a converter that transforms MCP tool schemas to OpenAI function calling format, preserving parameter types and descriptions.

Accomplishments We're Proud Of

  • Full MCP implementation from scratch - we learned the protocol deeply by building our own server
  • Working Gmail integration - secure OAuth flow with real email sending
  • Intelligent context retention - the AI genuinely remembers your conversation
  • Clean separation of concerns - MCP server, Flask host, and frontend are properly decoupled
  • Actually works end-to-end - you can send real emails through natural conversation!

What We Learned

Technical:

  • How the Model Context Protocol works at a low level (JSON-RPC, stdio transport, tool schemas)
  • Google OAuth 2.0 flow with token refresh mechanics
  • OpenAI function calling and how to convert tool schemas
  • Subprocess communication via stdin/stdout pipes
  • Flask session management for stateful conversations

Architectural:

  • The tradeoff between using SDK abstractions vs. building simple solutions
  • When to pivot from complex implementations to simpler working solutions
  • How to structure a host-client-server architecture for LLM tool calling

Practical:

  • Package management with uv in Python projects
  • The importance of conversation context for natural UX

What's Next for MailMind

Short-term:

  • Expand to Google Calendar (schedule meetings), Sheets (data queries), Drive (file search)
  • Add email templates for common scenarios
  • Implement email search and read capabilities

Production-ready features:

  • Replace subprocess spawning with persistent MCP connections using the SDK's ClientSession
  • Add Redis-backed conversation storage for multi-server deployments
  • Implement connection pooling for better performance
  • Convert to async architecture (Quart/FastAPI) for scalability
  • Add rate limiting and proper authentication
  • Support multiple email accounts per user

Advanced AI features:

  • Smart scheduling: "Find a time that works for everyone and send invites"
  • Email summarization: "What are my unread emails about?"
  • Action extraction: "What tasks do I need to complete from my emails?"

MailMind is just the beginning of making productivity tools truly conversational. We're excited to see where the Model Context Protocol takes human-AI collaboration!

Built With

Share this project:

Updates