# smailr-mcp

[English](#english) · [中文](#中文)

---

## English

An open-source [MCP](https://modelcontextprotocol.io) (Model Context Protocol) server for [Smailr](https://smailr.com) 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 | `list_mailboxes` · `create_mailbox` · `check_address` · `get_mailbox` · `update_mailbox` · `delete_mailbox` |
| Mails | `list_mails` · `get_mail` · `update_mail` · `delete_mail` · `search_mails` · `send_mail` |
| Attachments | `upload_attachment` |
| Contacts | `list_contacts` · `create_contact` |
| Folders | `list_folders` · `create_folder` |
| Labels | `list_labels` · `create_label` |
| Read-only | `list_rules` · `list_signatures` · `get_quota` · `get_stats` |

### 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):

```bash
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

```json
{
  "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

| Variable | Required | Description |
|---|---|---|
| `SMAILR_API_KEY` | yes | Your Smailr API key (`nm_...`) |
| `SMAILR_BASE_URL` | no | API base URL override (default `https://smailr.com/api/v1`) |

### Development

```bash
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](LICENSE)

---

## 中文

一个开源的 [MCP](https://modelcontextprotocol.io)（Model Context Protocol）服务器，把 [Smailr](https://smailr.com) 邮箱接入任何支持 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 登录**（不用进设置页）：

```bash
npx -y smailr-mcp auth
```

命令会自动打开浏览器进行 NodeLoc 授权。授权完成后浏览器会跳到一个 smailr.com 页面（可能显示报错，属正常现象）；把地址栏里的完整 URL 复制粘贴回终端，CLI 会自动为你创建一把 scoped API key，并打印出可直接复制的客户端配置。

### 第二步：配置 MCP 客户端

```json
{
  "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 发封邮件"
- "我的存储配额用了多少？"

### 环境变量

| 变量 | 必填 | 说明 |
|---|---|---|
| `SMAILR_API_KEY` | 是 | Smailr API key（`nm_...`） |
| `SMAILR_BASE_URL` | 否 | API 地址覆盖（默认 `https://smailr.com/api/v1`） |

### 本地开发

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

### 已知限制

- Smailr 的 OpenAPI 文档未定义响应 schema，工具输出为原始 JSON 透传
- 联系人/文件夹/标签上游只支持列出和创建；收信规则和签名为只读
- 上游没有 webhook 推送机制，新邮件场景需要轮询 `list_mails`

### 开源协议

[MIT](LICENSE)