smailr-mcp

English · 中文

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:

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 auth

This 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.json

• Cursor: 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

Development

git clone <repo-url>
cd smailr-mcp
npm install
npm run build
node test-stdio.mjs   # smoke test: MCP handshake + tools/list

Notes & 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

MIT

Related MCP server: Mail MCP Server

中文

一个开源的 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.json

• Cursor：设置 → MCP

• Cherry Studio / Cline：添加自定义 MCP server，填入同样的 JSON

重启客户端后即可直接对话：

• "列出我收件箱最新的 5 封邮件"

• "用 hello@我的域名 给 alice@example.com 发封邮件"

• "我的存储配额用了多少？"

环境变量

本地开发

git clone <仓库地址>
cd smailr-mcp
npm install
npm run build
node test-stdio.mjs   # 冒烟测试：MCP 握手 + 工具列表

已知限制

• Smailr 的 OpenAPI 文档未定义响应 schema，工具输出为原始 JSON 透传

• 联系人/文件夹/标签上游只支持列出和创建；收信规则和签名为只读

• 上游没有 webhook 推送机制，新邮件场景需要轮询 list_mails

开源协议

MIT