Configuration
Configuration
One TOML file. No secrets go in it — tokens and passwords live in your OS
keyring, with a 0600 file fallback on headless machines.
Where the file lives
Resolved in this order:
$RUBIT_MCP_MAIL_CONFIG(with~expanded)$XDG_CONFIG_HOME/rubit-mcp-mail/config.toml~/.config/rubit-mcp-mail/config.toml
On Windows that third path resolves to
%USERPROFILE%\.config\rubit-mcp-mail\config.toml — Path.home() / ".config"
works there too.
A complete example
download_dir = "~/Downloads/rubit-mcp-mail"
[accounts.outlook]
provider = "outlook"
email = "you@outlook.com"
client_id = "<Application (client) ID from your Azure app registration>"
# Any other IMAP server, e.g. Fastmail:
[accounts.personal]
provider = "generic"
email = "you@fastmail.com"
host = "imap.fastmail.com"
# port = 993 # default
# ssl = true # default
disabled_tools = ["get_attachment"]
# Optional: correct a compiled-in endpoint without waiting for a release.
[providers.outlook]
host = "outlook.office365.com"
Top level
| Key | Type | Default | Meaning |
|---|---|---|---|
download_dir | path | ~/Downloads/rubit-mcp-mail | Where get_attachment saves files. ~ is expanded. |
[accounts.<name>] | table | — | One per mailbox. The table name is the account name. |
[providers.<name>] | table | — | Endpoint overrides. |
Unknown top-level keys are an error, not a silent no-op.
[accounts.<name>]
| Key | Type | Default | Meaning |
|---|---|---|---|
provider | "outlook" | "generic" | "generic" | Which profile to start from. |
email | string | required | The address to sign in as. |
client_id | string | — | Required when provider = "outlook". The Azure Application (client) ID. |
host | string | — | Required for generic. IMAP host. |
port | int | 993 | |
ssl | bool | true | |
disabled_tools | string | [] | Tools forbidden for this account. See Permissions. |
Validation runs when the file is read, so a missing client_id or an unknown
tool name in disabled_tools fails loudly with the account named, rather than
at connection time.
Environment variables
| Variable | Effect |
|---|---|
RUBIT_MCP_MAIL_CONFIG | Use this config file instead of the default path. |
RUBIT_MCP_MAIL_NO_KEYRING | Skip the OS keyring; use ~/.config/rubit-mcp-mail/secrets.json (mode 0600) instead. Set it for both auth and serve, or they will disagree. |
RUBIT_MCP_MAIL_PASSWORD_<ACCOUNTNAME> | Supply an app password without ever storing it. Account name uppercased — [accounts.personal] → RUBIT_MCP_MAIL_PASSWORD_PERSONAL. |
RUBIT_MCP_MAIL_LOG_LEVEL | Server verbosity. DEBUG also reports each account's live auth status and why a silent token refresh failed. |
RUBIT_MCP_MAIL_LOG_FILE | Additionally log to this file. |
Editing it safely
You never have to hand-write TOML: the settings window reads and writes this exact file through the same parser the server uses.
Every write goes to a temporary file beside the target, is re-parsed by the real config loader, and is only then moved into place. A rejected edit leaves the original byte-for-byte, and comments, ordering and formatting survive a save.