renater-partage-mcp

An MCP (Model Context Protocol) stdio server that gives AI agents full management of Renater Partage academic mailboxes (prenom.nom@example.edu, prenom.nom@example2.edu, or any configured Renater domain) over IMAP (read, folders, attachments) and SMTP (send).

Warning — this connector can send mail. With the default readonly: false, an AI agent can send, delete, move and flag mail on your behalf, authenticated with your Renater SSO password. Every write tool (send, delete, move, folder management, flag) requires a user confirmation token before it executes — see Confirmation for write tools. If you only need to read mail, set readonly: true in config.yaml — see Read-only mode.

Setup

Requires Python >= 3.11 and uv.

uv sync
cp .env.example .env
chmod 600 .env
cp config.yaml.example config.yaml

Edit .env and set your mailbox password:

RENATER_PASSWORD=your-password

Edit config.yaml with your account(s) and the domain -> host map:

accounts:
  - email: prenom.nom@example.edu
domains:
  example.edu: mail.example.edu
  example2.edu: mail.example.edu
imap: { port: 993, ssl: true }
smtp: { port: 465, ssl: true }

Multiple accounts: list them under accounts and set RENATER_PASSWORD_2, RENATER_PASSWORD_3, ... in .env matched by account order.

Related MCP server: phison-mail-mcp

MCP client configuration

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "renater-partage": {
      "command": "uv",
      "args": ["run", "renater-partage-mcp"],
      "cwd": "/path/to/renater_partage_connector"
    }
  }
}

opencode

The project includes an opencode.json that auto-registers the MCP server when you open this directory in opencode. If you need to configure it globally instead:

{
  "mcp": {
    "renater-partage": {
      "type": "local",
      "command": ["uv", "run", "renater-partage-mcp"],
      "cwd": "/path/to/renater-partage-mcp",
      "enabled": true
    }
  }
}

The cwd must point to the project directory so config.yaml and .env are found. Alternatively set RENATER_CONFIG_PATH to the config file path.

Tools

Every tool accepts an optional account_email parameter to select a specific configured account (defaults to the first one). On failure a tool returns a structured error object {"error": code, "message": ..., "hint": ...} instead of crashing.

Confirmation for write tools

Every write tool (send, delete, move, folder management, flag) uses a two-step confirmation flow. The AI agent cannot execute a write action without explicit user approval.

1. The agent calls the tool with the action parameters.

2. The server returns {"needs_confirmation": true, "token": "<uuid>", "description": "...", "hint": "..."} and does not execute the action.

3. The agent presents the action to the user and asks for approval.

4. If approved, the agent calls the same tool again with confirm_token set to the token from step 2. The server then executes the action.

Tokens are single-use and expire after 5 minutes. A tool called with an invalid or expired token returns an invalid_token error.

Read tools (list_folders, list_messages, read_message, search_messages, download_attachment) execute immediately without confirmation.

Read-only mode

IMAP/SMTP on Renater partage authenticate with the password only (no 2FA — that gate exists only on the webmail SSO). To shrink the risk of a leaked password, you can expose only the read tools:

# config.yaml
readonly: true

With readonly: true the server registers only list_folders, list_messages, read_message, search_messages and download_attachment. The send/folder/message-management tools are not registered at all, so an AI agent (or a leaked password) cannot send, delete, move or flag mail. If the config file cannot be read at all, the server also fails safe and exposes only the read tools.

Restart the MCP server after changing this flag.

Security notes

• The password lives only in .env (git-ignored); keep it chmod 600.

• config.yaml contains no secrets.

• Destructive operations (delete_message, move_message) require an explicit message UID.

• Attachments are only written inside the dest_dir you pass (default downloads/); filenames are sanitized before writing.

Testing

uv run pytest            # unit tests (fakes, no network)
RENATER_LIVE_TEST=1 uv run pytest tests/test_live.py   # live check against the real server

Troubleshooting

• auth error: check RENATER_PASSWORD in .env (it must match your Renater SSO password).

• network error: check the IMAP/SMTP host and port in config.yaml (default mail.example.edu, IMAP 993, SMTP 465) and your network connectivity.

• folder_not_found / message_not_found: list folders or messages first to get the exact names and current UIDs.