MCP Email Orchestrator

An intelligent email orchestration system built using the Model Context Protocol (MCP), FastAPI, and Ollama. This project demonstrates how to seamlessly connect local Large Language Models (LLMs) to external tools—specifically, an SMTP email sender—using a standardized client-server architecture.

Table of Contents

• What is the Model Context Protocol (MCP)?
• Project Architecture
• LLM Integration
• What This Project Achieves
• Repository Structure
• Installation & Setup
• Usage

---

What is the Model Context Protocol (MCP)?

The Model Context Protocol (MCP) is an open standard introduced by Anthropic in November 2024. It provides a universal, standardized way for AI applications (like LLMs) to connect with external systems, data sources, and tools. Before MCP, developers had to write custom integrations for every new data source or tool they wanted their AI to use. MCP solves this by establishing a consistent, two-way communication protocol based on JSON-RPC 2.0.

MCP Client vs. MCP Server

MCP follows a strict client-server architecture:

• MCP Host / Client: The AI application or agent (in this project, the FastAPI orchestrator running the Ollama model). The client maintains a connection to the server, requests context, and asks the server to execute specific tools based on the LLM's reasoning.
• MCP Server: A lightweight program that exposes specific capabilities (Tools, Resources, or Prompts) to the client. In this project, the email_mcp_server.py acts as the MCP Server, exposing a send_email tool that handles the actual SMTP communication.

By separating the AI logic (Client) from the execution logic (Server), MCP ensures secure, modular, and scalable AI tool use.

---

Project Architecture

This project implements a complete MCP lifecycle using a local LLM:

1. FastAPI Orchestrator (The Host): main.py serves as the entry point. It manages the lifecycle of the MCP Server, spawning it as a subprocess via standard input/output (stdio) transport.
2. Dynamic Tool Discovery: Upon startup, the FastAPI app connects to the MCP Server, dynamically fetches the available tools (e.g., send_email), and translates the MCP tool schemas into a format that the Ollama LLM understands.
3. The LLM (Ollama): When a user sends a prompt via the /chat endpoint, the orchestrator passes the prompt and the available tools to the local LLM.
4. Tool Execution: If the LLM determines that an email needs to be sent, it returns a tool call request. The orchestrator routes this request back to the MCP Server.
5. MCP Server (The Executor): email_mcp_server.py receives the execution request, securely accesses the SMTP credentials from the environment, and sends the email.

---

LLM Integration

This project utilizes Ollama to run local, open-source models.

• Default Model: qwen2.5:1.5b
• Function Calling: The project leverages the native function-calling capabilities of modern LLMs. The system prompt explicitly instructs the model: "You are a helpful assistant. If the user wants to send an email, use the send_email tool."
• Bulletproof Extraction: The orchestrator includes robust parsing logic to handle the LLM's responses, ensuring that tool calls are accurately extracted whether the model returns them as dictionaries or Pydantic objects.

---

What This Project Achieves

1. Standardized AI Tooling: Demonstrates a working implementation of the newly released Model Context Protocol, moving away from hardcoded tool logic to dynamic discovery.
2. Local AI Privacy: By using Ollama, the reasoning engine runs entirely locally, ensuring that user prompts are not sent to third-party APIs.
3. Secure Credential Management: The MCP Server handles the sensitive SMTP credentials (.env), keeping them isolated from the LLM and the main orchestrator logic.
4. Extensibility: Because it uses MCP, adding new capabilities (like reading files, querying a database, or searching the web) is as simple as adding a new tool to the MCP Server—no changes to the core LLM routing logic are required.

---

Repository Structure

MCP_Email/
├── main.py                 # FastAPI app, MCP Client, and Ollama orchestrator
├── email_mcp_server.py     # FastMCP Server exposing the send_email tool
├── requirements.txt        # Python dependencies
├── .env                    # (Not tracked) SMTP credentials
└── tools/
    ├── email_tool.py       # Core SMTP execution logic
    └── mcp_registry.py     # Tool schemas and registry

---

Installation & Setup

Prerequisites

• Python 3.10+
• Ollama installed and running locally.
• The qwen2.5:1.5b model pulled in Ollama (ollama run qwen2.5:1.5b).

1. Clone the Repository

git clone https://github.com/SOUGUR/MCP_Email.git
cd MCP_Email

2. Install Dependencies

pip install -r requirements.txt

3. Configure Environment Variables

Create a .env file in the root directory and add your SMTP credentials:

SENDER_EMAIL=your_email@gmail.com
SENDER_PASSWORD=your_app_password
SMTP_SERVER=smtp.gmail.com
SMTP_PORT=587

---

Usage

1. Start the Orchestrator:

   python main.py
   

   Note: The FastAPI app will automatically spawn and connect to the MCP Server on startup.

2. Send a Request: You can interact with the system by sending a POST request to the /chat endpoint.

   curl -X POST "http://localhost:8000/chat" \
        -H "Content-Type: application/json" \
        -d '{"prompt": "Please send an email to test@example.com with the subject Hello and body This is a test from MCP."}'
   

3. Expected Output: The LLM will process the natural language request, trigger the send_email tool via the MCP Server, and return the execution results.