pylos-mcp

pylos-mcp

Your mail client shows you the message. pylos-mcp shows your assistant what it hides.

Warnings: sender_mismatch, hidden_text, instruction_patterns, mixed_script, encoded_blob

Reads and drafts by default. Sending starts off. No bcc anywhere.

Ask your assistant what needs you today, to sum up a long thread, or to draft the reply you keep putting off. pylos-mcp gives Claude, or any MCP client, your Gmail, Outlook and Microsoft 365, iCloud or IMAP mailbox to do it with.

Anyone can put text in your inbox, and once an AI assistant reads that inbox, they can put text in front of the assistant too. So every message reaches the assistant fenced as input from a stranger, with a Warnings line for what looks off, such as hidden text, phrases aimed at an AI, lookalike letters, a Reply-To on another domain or a failed DMARC check. The message in the image trips five detectors at once.

It runs on your machine. Moving, sending and deleting stay off until you turn them on, and sending then reaches only the recipients you allow.

Try it without a mailbox

--demo serves a sample inbox instead of yours. It holds a colleague's note with a deadline, a receipt, a newsletter, a parcel notice your mail server could not verify, and the account warning from the image above. The demo reads none of your settings and connects to no mail server, so there is nothing to sign in to.

claude mcp add pylos-demo -- npx -y pylos-mcp --demo

In other clients, add --demo to the args of the entry under Quick start and leave out env. Then ask the assistant whether anything in the inbox is urgent.

The newsletter shows a limit worth knowing. Its preview line is hidden from mail clients by design, so it gets a hidden_text warning too. A warning says what a message contains, not whether it is malicious.

Quick start

pylos-mcp works with any client that runs local MCP servers. It runs locally through npx and needs Node.js 22 or later. Every route below starts from example values, so replace the address and password with your own. Use an app password, not your account's regular password, and for Outlook no password at all. Provider setup says where to get one.

pylos-mcp connects to your mail provider, and with Outlook to Microsoft's sign in service. What the assistant reads goes to your AI client and, through it, to the model provider you use, as anything else you show your assistant does. Attachments you ask for are saved to your Downloads folder.

Claude Desktop. Download pylos-mcp.mcpb, open it, and fill in the form Desktop shows.

Claude Code. --scope user makes it available in every project. EMAIL_PASSWORD_CMD keeps the password out of your shell history and Claude's config: it runs a command that prints the password, here a macOS keychain lookup. Store the password there first with security add-generic-password -s pylos-mcp -a you@example.com -w, which asks for it.

claude mcp add pylos-mcp --scope user -e PROVIDER=gmail -e EMAIL_USER=you@example.com \

-e EMAIL_PASSWORD_CMD="security find-generic-password -s pylos-mcp -w" -- npx -y pylos-mcp

Cursor and VS Code. Use the buttons above, then put your own values in the config they create.

Config files for Cursor, VS Code, Windsurf, Cline and other clients

Most clients, Cursor's .cursor/mcp.json and Claude Desktop's claude_desktop_config.json among them, take this entry:

{

"mcpServers": { "pylos-mcp": { "command": "npx", "args": ["-y", "pylos-mcp"], "env": { "PROVIDER": "gmail", "EMAIL_USER": "you@example.com", "EMAIL_PASSWORD": "your-app-password" } } } }

VS Code's .vscode/mcp.json names the key servers:

{

"servers": { "pylos-mcp": { "command": "npx", "args": ["-y", "pylos-mcp"], "env": { "PROVIDER": "gmail", "EMAIL_USER": "you@example.com", "EMAIL_PASSWORD": "your-app-password" } } } }

Outlook and Microsoft 365 take PROVIDER=outlook and no password at all, so remove EMAIL_PASSWORD from the entry, or the server refuses to start. The first time the assistant reads mail, your browser opens Microsoft's sign in page.

Restart your client fully after any change, since tools register only at startup and toggling the server off and on is not always enough. Then ask the assistant to list your mail folders. A list means it works.

If the Claude Desktop extension shows "Server disconnected", the reason is in Desktop's main.log in ~/Library/Logs/Claude on macOS or %APPDATA%\Claude\logs on Windows, on a line starting with pylos-mcp:.

Why the defaults are what they are

Simon Willison calls it the lethal trifecta: an AI agent with access to private data, exposure to untrusted content and the ability to communicate externally. An assistant reading your email has the first two by design, because your inbox is private and anyone can write to it. Stealing what it read takes the third, a way to send it somewhere else.

Sending is off by default. Drafts wait in your Drafts folder until you send them yourself, and enabling sending still requires a recipient allowlist. With SEND_CONFIRM=true, every message is also shown to you in a dialog and goes out only if you accept. No tool attaches a file from your disk or adds a forwarding rule.

The third leg can still come from elsewhere in the same client, such as a tool that fetches web pages or runs shell commands. Image markup inside a message is neutralized, but the model can still write an image link of its own, which a client that loads images would fetch. When the assistant reads your mail, keep tools that reach the internet out of that conversation.

Fencing reduces prompt injection risk, and nothing eliminates it. The model still reads text written by strangers, so check what the assistant tells you about your mail before acting on it.

Capabilities

Each capability is a separate switch, and turning one on leaves the others as they are. Reading is always on, drafting starts on, and everything else stays off until you list it in CAPABILITIES. A tier that is off has its tools left out of the tool list entirely, so a model never learns they exist.

Enable more with a list, for example CAPABILITIES=drafts,manage,delete. Moving a message into Trash is a delete by another route, so move_email refuses Trash unless delete is on too.

get_thread lists the conversation a message belongs to, meaning the messages it replies to and the replies that name it or an earlier message, from its own folder, INBOX and Sent. Each message is then read with get_email, which adds its warnings. Both create_draft and send_email take in_reply_to to thread a reply under the original in mail clients. Sending the reply marks the original as answered. With quote_original, the server adds the original below the reply as mail clients do, but only when every recipient was already on the original. Text the original's HTML hid is left out. A message body can be at most 64 kB, quote included.

search_emails pages through results filtered by free text, from, to, subject, since and before dates, or unread and flagged status. get_email shows sent and arrival times, Cc, and Reply-To when it differs from From. With manage on, set_flags marks messages read, unread, flagged or unflagged.

get_attachment saves a file to DOWNLOAD_DIR without reading its contents into the conversation. Saved files are readable only by you, never replace an existing file, and on macOS carry the quarantine flag, so an app among them goes through Gatekeeper before it runs.

What this can never do

These limits are enforced by the server.

• No raw HTML reaches the model. Bodies come from the plain text part when one exists, or are converted to text otherwise. Invisible characters that hide instructions from a reader while staying readable to a model are stripped.
• Bodies, subjects, sender names and Sieve scripts are fenced with markers that are neutralized inside the content, so a message cannot forge its way out. The server writes the lines outside the fence. Any short mailbox value repeated there