# MCP Email Server

A production-ready [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that empowers AI agents to securely send emails via SMTP. 

This project bridges the gap between foundation models and real-world communication by providing a clean, typed, and verifiable Email Tool compatible with major agent frameworks like **LangChain**, **AutoGen**, and **CrewAI**, or direct use with Claude Desktop.

### Is this compatible with any AI model?
**Yes.** As long as the framework interacting with the AI supports the Model Context Protocol (MCP) or standard function calling (which almost all modern LLMs like GPT-5, Claude, and Gemini do), your agent can command this server to send an email!

The **Model Context Protocol (MCP)** is an open standard that enables AI models to interact with local systems, databases, and APIs. Instead of giving an AI model raw access to your computer or forcing developers to write bespoke API integrations for every new LLM, MCP provides a standard protocol. 

**Why use this MCP Email Server?**
When your AI agent needs to email a report, notify a user, or summarize data, it can simply call the `send_email` tool exposed by this server. This cleanly separates the LLM logic from the messy realities of SMTP handshakes, TLS, and credential management.

---

## ✨ Features

* **SMTP Support:** Send emails using Gmail, Outlook, or any standard SMTP provider.
* **Rich Capabilities:** Supports plain text, HTML emails, and file attachments natively.
* **Security First:** Strict enforcement of environment variable usage—no hardcoded credentials. 
* **Safe Logging:** Ensures logs don’t leak credentials while keeping stderr clean for MCP's internal JSON-RPC communication on stdout.
* **Robust Validation:** Pydantic models automatically validate tool inputs before the SMTP connection is attempted.

---

## 🚀 Installation & Setup

### 1. Install the Server

Clone the repository and install it using pip (requires Python 3.9+). 
*Using a virtual environment is strongly recommended.*

```bash
git clone https://github.com/yashjoshiatgit/email-mcp.git
cd email-mcp
pip install -e .
```

### 2. Environment Configuration

Copy the example environment file and configure your SMTP credentials:

```bash
cp .env.example .env
```

Edit the `.env` file:
```ini
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USERNAME=your_email@gmail.com
# IMPORTANT: Use an App Password, not your real password!
SMTP_PASSWORD=abcd1234efgh5678
```

## 🛠️ Usage

### Testing the Server Locally (MCP Inspector)

Before deploying this server to your AI agents, it's a good idea to test it yourself. Because an MCP server speaks JSON-RPC over standard input/output (and not over HTTP like a regular web api), the easiest way to test it is with the official MCP Inspector.

1. Install the MCP Inspector (requires Node.js):
```bash
npx @modelcontextprotocol/inspector email-mcp
```
2. Open the UI link it provides in your terminal (usually `http://localhost:5173`).
3. Go to the **Tools** tab.
4. Click on the `send_email` tool.
5. Provide a test JSON payload like this:
```json
{
  "to": "test@example.com",
  "subject": "Hello from MCP",
  "body": "This is a test email sent from the MCP Inspector UI!"
}
```
6. Click **Run Tool**. If configured correctly, the email will be sent immediately!

---

### Framework Integrations

#### Claude Desktop

You can integrate this directly into Claude Desktop by editing your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "email": {
      "command": "email-mcp"
    }
  }
}
```
*(Make sure `email-mcp` is in your system PATH, or provide the absolute path to your `.venv/Scripts/email-mcp.exe`)*

#### LangChain
Integrating this server into LangChain allows your agent to say "I've emailed the report to the manager."

Check out the conceptual setup in: [`examples/langchain_agent.py`](examples/langchain_agent.py)

#### AutoGen
Allow multi-agent conversations to trigger external notifications when consensus is reached.

Check out the conceptual setup in: [`examples/autogen_agent.py`](examples/autogen_agent.py)

---

## 🤝 Contribution Guidelines

We welcome contributions! Please follow these steps:
1. Fork the repository.
2. Create your feature branch (`git checkout -b feature/AmazingFeature`).
3. Ensure you have installed dev dependencies (`pip install -e ".[dev]"`).
4. Run tests before committing (`pytest tests/`).
5. Open a Pull Request.

Make sure your code adheres to standard Python typing and includes docstrings.

## License

Distributed under the MIT License. See `LICENSE` for more information.