# thunderbird-mcp-server

An MCP (Model Context Protocol) server that gives AI assistants like Claude the ability to send, read, and search emails directly — no UI automation, no browser extensions, just clean IMAP/SMTP over SSL.

Built for [Claude Code](https://docs.anthropic.com/en/docs/claude-code), but works with any MCP-compatible client.

## What it does

Instead of driving an email client's UI with clicks and keystrokes, this server exposes email operations as **structured tools** that an AI assistant can call programmatically:

```
You: "list my recent emails"
Claude Code → calls list_emails() via MCP → IMAP fetch → structured results
```

## Tools

| Tool | Description |
|------|-------------|
| `send_email` | Send an email with To, Subject, Body, optional CC/BCC |
| `list_emails` | List recent emails in any folder (INBOX, Sent, Drafts, etc.) |
| `read_email` | Read the full content of a specific email by ID |
| `search_emails` | Search emails by subject or sender |
| `list_folders` | List all available mail folders |

## Architecture

```
┌─────────────┐   stdio (JSON-RPC)   ┌──────────────┐   IMAP/SMTP (SSL)   ┌─────────────┐
│ Claude Code  │ ◄──────────────────► │  server.py   │ ◄────────────────► │ Mail Server  │
│ (MCP Client) │                      │ (MCP Server) │                    │ (any IMAP)   │
└─────────────┘                       └──────────────┘                    └─────────────┘
```

- **Transport:** stdio with JSON-RPC — Claude Code launches the server as a subprocess
- **Reading:** IMAP4_SSL (port 993) — encrypted connection, server-side search
- **Sending:** SMTP_SSL (port 465) — encrypted, authenticated relay
- **Auth:** credentials via environment variables, never hardcoded

## Setup

### Prerequisites

- Python 3.9+
- An IMAP/SMTP email account

### 1. Clone and install

```bash
git clone https://github.com/yuvi2118/thunderbird-mcp-server.git
cd thunderbird-mcp-server
python3 -m venv venv
source venv/bin/activate
pip install "mcp[cli]>=1.0.0"
```

### 2. Configure

Copy the example env file and fill in your credentials:

```bash
cp .env.example .env
# Edit .env with your email credentials
```

### 3. Register with Claude Code

```bash
claude mcp add email -s user \
  -e EMAIL_USER=your_username \
  -e EMAIL_PASS=your_password \
  -e EMAIL_IMAP_SERVER=your.mail.server \
  -e EMAIL_SMTP_SERVER=your.mail.server \
  -e "EMAIL_FROM_NAME=Your Name" \
  -- python3 /path/to/thunderbird-mcp-server/server.py
```

Restart Claude Code. The email tools are now available in every session.

### 4. Test with MCP Inspector

```bash
npx @modelcontextprotocol/inspector -- bash run.sh
```

Opens a web UI at `localhost:6274` where you can call each tool interactively.

## Configuration

All configuration is via environment variables:

| Variable | Required | Description |
|----------|----------|-------------|
| `EMAIL_USER` | Yes | IMAP/SMTP login username |
| `EMAIL_PASS` | Yes | IMAP/SMTP login password |
| `EMAIL_IMAP_SERVER` | Yes | IMAP server hostname |
| `EMAIL_SMTP_SERVER` | Yes | SMTP server hostname |
| `EMAIL_IMAP_PORT` | No | IMAP port (default: 993) |
| `EMAIL_SMTP_PORT` | No | SMTP port (default: 465) |
| `EMAIL_FROM_NAME` | No | Display name in sent emails |
| `EMAIL_FROM_ADDR` | No | From address in sent emails |

## Screenshots

### MCP Inspector — listing emails
![MCP Inspector listing emails](images/inspector-list-emails.png)

### MCP Inspector — sending email
![MCP Inspector sending email](images/inspector-send-email.png)

### Claude Code — live demo
![Claude Code using email tools](images/claude-code-demo.png)

## Usage examples

Once registered, just talk naturally in Claude Code:

```
> list my emails
> read email 748
> search emails from "professor name"
> send an email to john@example.com about the meeting tomorrow
> show my sent folder
```

## Tech stack

- **Python** — standard library only (imaplib, smtplib, email) + MCP SDK
- **MCP SDK** — compatible with both v1 (`FastMCP`) and v2 (`MCPServer`)
- **Security** — SSL/TLS for all connections, credentials via env vars following 12-factor principles

## License

MIT