# evolution-mcp

MCP server for GNOME Evolution -- exposes calendar and email functionality
via the [Model Context Protocol](https://modelcontextprotocol.io) using
Evolution Data Server (EDS).

## Requirements

- Python >= 3.10
- GNOME Evolution Data Server (EDS) 1.2+
- System packages: `gir1.2-camel-1.2`, `gir1.2-edataserver-1.2`, `gir1.2-ecal-2.0`
- Credentials stored in GNOME Keyring (auto-configured when accounts are set up in Evolution)

## Installation

```bash
uv sync
```

Or with pip:

```bash
pip install -e .
```

## Configuration

Add to your MCP client configuration (e.g. `.mcp.json`):

```json
{
  "mcpServers": {
    "evolution": {
      "command": "uv",
      "args": ["--directory", "/path/to/evolution-mcp", "run", "evolution-mcp"]
      "env": {
        "DBUS_SESSION_BUS_ADDRESS": "unix:path=/run/user/1000/bus",
        "DISPLAY": ":0"
      }
    }
  }
}
```

## Tools

### Calendar

| Tool | Description |
|------|-------------|
| `list_calendars` | List all enabled calendars with UID, name, color, and backend |
| `list_events` | Query events in a date range (`calendar_uid`, `start_date`, `end_date`) |
| `get_event` | Get full details of a single event (`calendar_uid`, `event_uid`) |
| `create_event` | Create a new event (`calendar_uid`, `summary`, `start_datetime`, `end_datetime`, optional `description`, `location`) |
| `update_event` | Update an existing event (fetch-modify-save) |
| `delete_event` | Delete an event (`calendar_uid`, `event_uid`) |

### Email

| Tool | Description |
|------|-------------|
| `list_mail_accounts` | List all configured mail accounts with UID, name, email, and backend |
| `list_mail_folders` | List all folders in an account with unread/total counts |
| `list_messages` | Paginated message summaries from a folder (newest first) |
| `read_message` | Full message with plain/HTML body and attachment list |
| `search_messages` | Search by subject, from, or body text |
| `send_email` | Send an email (Camel transport with smtplib fallback) |
| `move_message` | Move a message between folders |
| `mark_message` | Set flags: `read`, `unread`, `flagged`, `unflagged`, `deleted` |

## Architecture

```
evolution-mcp
  FastMCP (stdio JSON-RPC)
    _MCPCamelSession (Camel.Session subclass)
      authenticates via GNOME Keyring / ESourceCredentialsProvider
      ECal.Client  -- calendar CRUD
      Camel.Store  -- IMAP/POP mail access
```

- **Single-threaded EDS access** -- all EDS/Camel calls are serialised
  through a single-worker `ThreadPoolExecutor` (EDS is not thread-safe).
- **Async bridge** -- each MCP tool wraps blocking EDS calls with
  `asyncio.to_thread()`.
- **Authentication** -- `_MCPCamelSession` looks up stored passwords via
  `ESourceCredentialsProvider` and calls `service.authenticate_sync()` to
  perform the actual protocol authentication (IMAP LOGIN, etc.).
- **IMAPX online mode** -- IMAPX stores are `CamelOfflineStore` subclasses
  that require `set_online_sync(True)` to connect. The IMAPX connection
  manager checks both `session.online` and `store.online` before allowing
  operations.
- **Folder tree walking** -- `CamelFolderInfo` child/next pointers are
  exposed as raw C pointers by PyGObject, so ctypes is used to dereference
  and walk the tree.

## License

See [LICENSE](LICENSE) for details.