OpenMail MCP server
Commit Nov 13, 2026Allows AI agents to manage email inboxes, read messages, reply in-thread, and handle attachments.
Also known as openmailsh/mcp, mcp
- Stars
- 1
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 0.1.0
- Last commit
- Nov 13, 2026
- License
- MIT
What is OpenMail MCP?
OpenMail allows AI agents to manage email inboxes, read messages, reply in-thread, and handle attachments.
Summary generated from the project's README
About OpenMail MCP server
Managing email inboxes and responding to messages directly from an AI agent is what OpenMail enables. This hosted streamable HTTP MCP server provides a single inbox where agents can read incoming mail that requires a response and reply within existing threads. It is designed for developers using Claude via OAuth, Cursor, or Claude Code, as well as headless agents that connect using an API key.
Users can interact with attachments through specific tools like get_attachment, which handles images as image content and other files as embedded resources up to a 4 MB inline limit. For text-heavy files, the get_attachment_text tool extracts only the text content. While Claude and Cursor users can connect via OAuth, developers using stdio-only clients should utilize mcp-remote to access the service. The server supports different access levels, including a read-only option via the /mcp/readonly endpoint.
What you can do with it
- 1Managing email threadsAsk your AI agent to find messages that need a response and reply to them within the same thread.
- 2Processing email attachmentsHave an agent extract text from a document attached to an email or view an image sent in a message.
Written from the project's README. Every use case is checked against a quote from it.
How to install OpenMail MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall OpenMail MCP in Claude Code
$ claude mcp add --transport http mcp https://mcp.openmail.sh/mcpInstall OpenMail MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"mcp": {
"url": "https://mcp.openmail.sh/mcp"
}
}
}Install OpenMail MCP in VS Code
.vscode/mcp.json
{
"servers": {
"mcp": {
"type": "http",
"url": "https://mcp.openmail.sh/mcp"
}
}
}Install OpenMail MCP in VS Code CLI
$ code --add-mcp '{"name":"mcp","type":"http","url":"https://mcp.openmail.sh/mcp"}'Install OpenMail MCP in Codex
$ codex mcp add mcp --url https://mcp.openmail.sh/mcpInstall OpenMail MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.mcp] url = "https://mcp.openmail.sh/mcp"
Install OpenMail MCP in Gemini CLI
$ gemini mcp add -s user --transport http mcp https://mcp.openmail.sh/mcpInstall OpenMail MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"mcp": {
"url": "https://mcp.openmail.sh/mcp",
"type": "http"
}
}
}Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableopenmailsh/mcp is public and reachablegithub.com/openmailsh/mcp ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-13github.com/openmailsh/mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeHTTPS endpoint answered 401 (sign-in required)Pass
README
View on GitHubOpenMail MCP
Hosted Streamable HTTP MCP at https://mcp.openmail.sh/mcp. Email inbox for AI agents: one inbox, read mail that wants a reply, reply in-thread.
Attachments: get_attachment returns the file (images as image content, other files as an embedded resource, 4 MB inline limit). get_attachment_text returns extracted text only.
There is no local stdio catalog — stdio-only clients should use mcp-remote.
Connect
Claude (OAuth): paste https://mcp.openmail.sh/mcp
Cursor (OAuth): Add to Cursor, or add the URL below without headers. Also on cursor.directory as a plugin (.cursor-plugin/plugin.json + mcp.json).
Claude Code: claude mcp add --transport http openmail https://mcp.openmail.sh/mcp, or install as a plugin (claude plugin marketplace add openmailsh/mcp, then claude plugin install openmail@openmailsh-mcp): the plugin bundles the server with the openmail skill, which teaches the agent when to reach for email and how to handle a thread. The plugin lives in plugin/ and holds only Markdown, JSON and the logo: the Claude directory refuses code files from unverified organisations, so keep code out of it.
VS Code / any registry client: listed in the MCP Registry as sh.openmail/openmail.
Cursor or headless agents (API key):
{
"mcpServers": {
"openmail": {
"url": "https://mcp.openmail.sh/mcp",
"headers": { "Authorization": "Bearer om_YOUR_KEY" }
}
}
}
Prefer an inbox-scoped key. Read-only: /mcp/readonly. One inbox: /mcp/inbox/{id}.
Keys and transcripts: over OAuth (Claude, Cursor sign-in) setup_agent_email and mint_inbox_key never return a token — the session is already authenticated, and anything returned lands in the chat. They point to the console, which shows a new key once in the browser. Over an API key (headless agent) the token is returned in the tool result; move it to the agent's env.
stdio-only clients: npx -y mcp-remote https://mcp.openmail.sh/mcp
Env
| Name | Purpose |
|---|---|
OPENMAIL_API_URL |
API origin (https://api.openmail.sh) |
MCP_RESOURCE_URL |
OAuth resource (https://mcp.openmail.sh) |
MCP_JWT_SECRET |
Same secret as the API. Required in production; outside production falls back to NEXTAUTH_SECRET |
CONSOLE_ORIGIN |
Consent page host |
PORT |
Listen port |
POSTHOG_API_KEY |
Turns on PostHog MCP Analytics ($mcp_tool_call per call). Unset = off |
MCP_ANALYTICS_DEBUG |
Set to log every captured analytics event |
See .env.example.
Local
pnpm install
pnpm test
pnpm dev
Contributing
Open an issue or PR. Run pnpm typecheck && pnpm test before pushing.
MIT © OpenMail
OpenMail MCP questions
How do I add OpenMail MCP to Claude Code?
Run claude mcp add --transport http mcp https://mcp.openmail.sh/mcp in your terminal. Add --scope user to make it available in every project.
How do I add OpenMail MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
How can I handle email attachments?
You can use get_attachment to return files (images as image content, others as embedded resources) or get_attachment_text to return only the extracted text.
How do I use an API key for headless agents?
You can configure your MCP settings with an Authorization header containing your Bearer token.