evolution-mcp

MCP server for GNOME Evolution -- exposes calendar and email functionality via the Model Context Protocol 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

uv sync

Or with pip:

pip install -e .

Configuration

Add to your MCP client configuration (e.g. .mcp.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 for details.