smailr-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@smailr-mcp List unread emails in my inbox"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
smailr-mcp
English
An open-source MCP (Model Context Protocol) server for Smailr mail. It lets any MCP-compatible AI client — Claude Desktop, Cursor, Cherry Studio, Cline, … — read, search and send email through natural language.
Local-first: the server runs on your machine over stdio. Your API key never leaves your computer.
Features
23 tools covering the full Smailr API:
Group | Tools |
Mailboxes |
|
Mails |
|
Attachments |
|
Contacts |
|
Folders |
|
Labels |
|
Read-only |
|
Requirements
Node.js ≥ 18
A Smailr account
Step 1 — Get an API key
Pick one of the two ways:
Option A — manual: Smailr web console → Settings → Developer → create an API key (nm_...).
Option B — NodeLoc OAuth (no settings page needed):
npx -y smailr-mcp authThis opens your browser for NodeLoc authorization. After authorizing, the browser lands on a smailr.com page (it may show an error — that's expected); copy the full URL from the address bar and paste it back into the terminal. The CLI then creates a scoped API key for you and prints a ready-to-paste client config.
Step 2 — Configure your MCP client
{
"mcpServers": {
"smailr": {
"command": "npx",
"args": ["-y", "smailr-mcp"],
"env": { "SMAILR_API_KEY": "nm_your_key_here" }
}
}
}Config file locations:
Claude Desktop:
claude_desktop_config.jsonCursor: Settings → MCP
Cherry Studio / Cline: add a custom MCP server with the same JSON
Restart the client, then ask things like:
"List the 5 newest mails in my inbox"
"Send an email from hello@mydomain.com to alice@example.com"
"How much storage quota have I used?"
Environment variables
Variable | Required | Description |
| yes | Your Smailr API key ( |
| no | API base URL override (default |
Development
git clone <repo-url>
cd smailr-mcp
npm install
npm run build
node test-stdio.mjs # smoke test: MCP handshake + tools/listNotes & limitations
The Smailr API defines no response schemas in its OpenAPI spec, so tool outputs are passed through as raw JSON.
Contacts/folders/labels support list + create only (no update/delete in the upstream API); rules and signatures are read-only.
There is no webhook/push mechanism upstream; new-mail workflows require polling
list_mails.
License
Related MCP server: phison-mail-mcp
中文
一个开源的 MCP(Model Context Protocol)服务器,把 Smailr 邮箱接入任何支持 MCP 的 AI 客户端——Claude Desktop、Cursor、Cherry Studio、Cline 等。装上之后,直接用自然语言收发、搜索、管理邮件。
本地优先:服务器以 stdio 方式运行在你自己的电脑上,API key 不经过任何第三方服务器。
功能
23 个工具,覆盖 Smailr 全部 API:邮箱管理(6)、邮件读写/搜索/发送(6)、附件上传(1)、联系人(2)、文件夹(2)、标签(2)、只读接口(收信规则、签名、配额、统计,共 4)。
环境要求
Node.js ≥ 18
一个 Smailr 账号
第一步:获取 API key(二选一)
方式 A — 手动:Smailr 控制台 → 设置 → 开发者 → 创建 API key(nm_...)。
方式 B — NodeLoc OAuth 登录(不用进设置页):
npx -y smailr-mcp auth命令会自动打开浏览器进行 NodeLoc 授权。授权完成后浏览器会跳到一个 smailr.com 页面(可能显示报错,属正常现象);把地址栏里的完整 URL 复制粘贴回终端,CLI 会自动为你创建一把 scoped API key,并打印出可直接复制的客户端配置。
第二步:配置 MCP 客户端
{
"mcpServers": {
"smailr": {
"command": "npx",
"args": ["-y", "smailr-mcp"],
"env": { "SMAILR_API_KEY": "nm_你的key" }
}
}
}Claude Desktop:写入
claude_desktop_config.jsonCursor:设置 → MCP
Cherry Studio / Cline:添加自定义 MCP server,填入同样的 JSON
重启客户端后即可直接对话:
"列出我收件箱最新的 5 封邮件"
"用 hello@我的域名 给 alice@example.com 发封邮件"
"我的存储配额用了多少?"
环境变量
变量 | 必填 | 说明 |
| 是 | Smailr API key( |
| 否 | API 地址覆盖(默认 |
本地开发
git clone <仓库地址>
cd smailr-mcp
npm install
npm run build
node test-stdio.mjs # 冒烟测试:MCP 握手 + 工具列表已知限制
Smailr 的 OpenAPI 文档未定义响应 schema,工具输出为原始 JSON 透传
联系人/文件夹/标签上游只支持列出和创建;收信规则和签名为只读
上游没有 webhook 推送机制,新邮件场景需要轮询
list_mails
开源协议
Available Tools
23 toolscheck_addressA
Check whether a mailbox address is available. Scope: mailbox:read
Inputs: address (required).
create_contactB
Create a contact. Scope: contact:write
Inputs: name (required), email (required).
create_folderB
Create a folder in a mailbox. Scope: folder:write
Inputs: name (required), mailbox_id (required).
create_labelC
Create a label. Scope: tag:write
Inputs: name (required), color.
create_mailboxB
Create a new mailbox. Scope: mailbox:write
Inputs: local_part (required), domain_id.
delete_mailC
Delete a mail. Scope: mail:manage
Inputs: id (required).
delete_mailboxB
Delete a mailbox permanently. Scope: mailbox:write
Inputs: id (required).
get_mailA
Get full details of a single mail. Scope: mail:read
Inputs: id (required).
get_mailboxA
Get mailbox details by ID. Scope: mailbox:read
Inputs: id (required).
get_quotaA
Get storage quota usage. Scope: storage:read
Inputs: no named parameters.
get_statsB
Get account statistics. Scope: storage:read
Inputs: no named parameters.
list_contactsB
List contacts. Scope: contact:read
Inputs: no named parameters.
list_foldersA
List folders of a mailbox. Scope: folder:read
Inputs: mailbox_id (required).
list_labelsA
List labels. Scope: tag:read
Inputs: no named parameters.
list_mailboxesA
List all Smailr mailboxes. Scope: mailbox:read
Inputs: no named parameters.
list_mailsB
List mails in a mailbox, optionally filtered by folder. Scope: mail:read
Inputs: mailbox_id (required), page, folder, per_page.
list_rulesA
List incoming-mail filter rules. Scope: filter:read
Inputs: no named parameters.
list_signaturesA
List mail signatures. Scope: signature:read
Inputs: no named parameters.
search_mailsA
Full-text search across mails. Scope: mail:read
Inputs: q (required).
send_mailC
Send an email from a mailbox. Scope: mail:send
Inputs: to (required), mailbox_id (required), cc, bcc, +5 more.
update_mailA
Update mail state (e.g. read/unread, flags, folder). Scope: mail:manage
Inputs: id (required), patch (required).
update_mailboxB
Update a mailbox (settings such as display name, signature, etc.). Scope: mailbox:write
Inputs: id (required), patch (required).
upload_attachmentA
Upload a local file as a mail attachment; returns an attachment ID for send_mail. Scope: attachment:write
Inputs: file_path (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 23 tools
Most tools are clearly resource-action pairs, but get_quota and get_stats both cover storage/account usage and list_mails/search_mails could be confused when searching a single mailbox. These are minor boundary cases; the rest are distinct.
All tools use lowercase snake_case verb_noun names (list_, create_, get_, update_, delete_, search_, send_, upload_, check_). Naming is uniform and predictable across all 23 tools.
23 tools is within the heavy range for an MCP server. The email domain is broad enough to justify many of them, but the count feels slightly bloated because several resource areas have only partial operations.
Mailboxes and mails have solid lifecycle coverage, but contacts, labels, and folders only support list/create, while rules and signatures are read-only. Agents cannot update or delete these secondary resources, which is a significant gap for full email management.
Maintenance
Related MCP Connectors
Email infrastructure for AI agents — send, receive, search, and reply to email over MCP.
Email inboxes for AI agents: send, receive, reply, search, and manage threaded email over MCP.
Email: search, read, fetch attachments; attach files when the MCP client supports inputs.
Email and optional phone for AI agents: send, receive, search, draft and call over MCP.
Related MCP Servers
- AlicenseBqualityCmaintenanceEnables users to manage email accounts via IMAP/SMTP, including reading, searching, sending emails with attachments and calendar invites, all through natural language interactions with MCP-compatible clients.136 PyPI4MIT
- FlicenseBqualityCmaintenanceEnables AI models to send, receive, search, and manage emails via SMTP/IMAP, including support for attachments, contacts, and advanced search.18-
- AlicenseNot gradedqualityCmaintenanceConnects any IMAP/SMTP mailbox to AI agents via MCP, enabling email read, search, send, reply, and management through natural language.11 npmMIT
- AlicenseBqualityBmaintenanceConnects MCP clients to any IMAP/SMTP email account, enabling email search, reading, sending, replying, forwarding, flagging, moving, and folder management via natural language.17MIT