Troubleshooting
Troubleshooting
Start with rubit-mcp-mail doctor. If that passes in a terminal but the server
fails inside Claude, the problem is almost always the environment — read on.
The startup summary
serve logs a startup summary to stderr, which Claude Desktop captures in
~/.config/Claude/logs/mcp-server-<name>.log and Claude Code shows with
claude --mcp-debug. It names the config path, the secret backend in use, and
whether each account's credential was found:
config: /home/you/.config/rubit-mcp-mail/config.toml (found)
secrets: keyring (keyring.backends.SecretService)
account outlook <you@outlook.com> via outlook: credential present (key 'msal-cache:outlook')
For more, set RUBIT_MCP_MAIL_LOG_LEVEL=DEBUG (and optionally
RUBIT_MCP_MAIL_LOG_FILE=/tmp/rubit-mail.log) in the env block; at DEBUG the
server also reports each account's live auth status, including why a silent
token refresh failed.
Reproducing the client's environment
To watch it by hand, run the server in the foreground with the same stripped environment the client uses:
env -i HOME="$HOME" USER="$USER" PATH=/usr/local/bin:/usr/bin:/bin \
RUBIT_MCP_MAIL_LOG_LEVEL=DEBUG ./.venv/bin/rubit-mcp-mail serve
credential NOT FOUND while rubit-mcp-mail doctor in your
terminal prints auth ok, the mismatch is the environment, not the token —
compare the secrets: line from each. The fix is in
Register with Claude → Linux.Common symptoms
| Symptom | Likely cause |
|---|---|
Every account reports "not authenticated" inside Claude Desktop, but doctor says auth ok | Stripped environment: keyring can't reach the Secret Service. Pass DBUS_SESSION_BUS_ADDRESS and XDG_RUNTIME_DIR, or set RUBIT_MCP_MAIL_NO_KEYRING=1 on both sides. |
| Outlook device-code sign-in fails immediately | Allow public client flows was not set to Yes in the Azure app registration (step 5). |
| Outlook rejects the sign-in outright | Supported account types is single-tenant. It must be "any organizational directory and personal Microsoft accounts" (step 3). |
posix_spawn cannot find the binary | Trailing or leading whitespace around the path in claude mcp add. |
folder: "junk" finds nothing | The server didn't advertise SPECIAL-USE and the name didn't match. Run doctor to see the classification, and use the raw folder name. |
| A permission toggle had no effect | The running serve process cached its config. Restart the client. |
A tool returns Error: '<tool>' is disabled for account '<name>' | It is in that account's disabled_tools. |
| Windows Defender or Avast flags the installer | Known false positive for unsigned PyInstaller binaries. |
Still stuck? Open an issue or get in touch.