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)

Related MCP server: ical-mcp

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

Email

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.