PyData_Boston_2025_MCP_Server_Tutorial

This MCP server provides an automated Gmail-enabled workflow accessible through the MCP Inspector. It exposes three tools: read_unread_emails, write_reply, and send_email. read_unread_emails fetches unread messages from your Gmail inbox (with a configurable max_results). write_reply uses OpenAI to generate a crafted reply based on the original email content and an optional persona prompt, returning the generated reply text. send_email sends an email via Gmail SMTP given a recipient, subject, and body. Together, these tools enable AI-assisted email reading, composing, and sending directly from the MCP interface. The available prompts include an email_agent_persona that tailors the assistant’s behavior for friendly, persona-driven responses. You can test end-to-end by first reading emails, then generating a reply, and finally sending a composed message, all via the MCP Inspector’s web UI.

Prerequisites:

• Python installed (recommended via your system package manager or pyenv).
• Access to a Gmail account with App Passwords enabled (for SMTP access).
• Optional: uv (a Python package installer/resolver) if you follow the provided setup approach in the tutorial.

Installation steps:

1. Clone or download the project directory (pydata_mcp_tutorial).
2. Set up a Python virtual environment:
   • python -m venv .venv
   • source .venv/bin/activate
3. Install MCP and OpenAI dependencies (via uv approach or direct pip):
   • If using uv as described in the tutorial: curl -LsSf https://astral.sh/uv/install.sh | sh uv init uv venv source .venv/bin/activate uv add mcp openai
   • Alternatively, install via pip if you have a requirements file (if provided): pip install -r requirements.txt # if such a file exists
4. Prepare environment variables in a .env file in the project root with: EMAIL_ADDRESS=your-email@gmail.com EMAIL_APP_PASSWORD=your-gmail-app-password OPENAI_API_KEY=your-openai-api-key
5. Run the MCP server (using Python command as configured): python gmail_mcp_server.py
6. (Optional) If using the MCP Inspector for testing, start the inspector as described in the tutorial and connect to the running server.

Notes and tips:

• Ensure Gmail App Passwords are generated with 2-Step Verification enabled for Gmail SMTP access (as described in the tutorial).
• The server uses the OpenAI API; keep your OPENAI_API_KEY secure and monitor usage to avoid unexpected costs.
• If you switch from a local run to a Codespace or remote environment, you may need to adjust inspector proxy addresses and allowed origins accordingly.
• The environment variables in .env are loaded by the server at startup; ensure they are present before launching.
• If you encounter JSON-RPC transport issues, verify that the server process is accessible on stdio and that the MCP Inspector is configured to connect to the correct port/address.